> ## Documentation Index
> Fetch the complete documentation index at: https://www.ayrshare.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Anúncios

> Gerencie anúncios impulsionados pela API GraphQL da Ayrshare com um único conjunto de operações que recebe a plataforma de anúncios como argumento.

As operações de anúncios recebem a plataforma de anúncios como argumento, então a mesma operação funciona em todas as plataformas de anúncios suportadas pela Ayrshare. Hoje, são `FACEBOOK` e `INSTAGRAM`.

Cada operação chama o [endpoint REST de anúncios](/docs/apis/ads/overview) correspondente e retorna sua resposta sem alterações. Autenticação e limites são os mesmos do REST. Uma chamada com falha retorna um erro GraphQL: `extensions.status` traz o status do REST, e `extensions.code` traz o código de erro da Ayrshare quando o erro REST tiver um. Veja [Erros](/docs/apis/graphql/errors). As operações de anúncios exigem o complemento Ads. Sem ele, toda chamada retorna um erro com `extensions.status` `403` e `extensions.code` `399`.

<h2 id="operations">
  Operações
</h2>

| Operação | Tipo | Endpoint REST |
| - | - | - |
| `adAccounts` | Query | `GET /ads/{platform}/accounts` |
| `adTargetingSearch` | Query | `GET /ads/{platform}/interests`, `/regions` ou `/cities` |
| `ads` | Query | `GET /ads/{platform}/ads` |
| `adHistory` | Query | `GET /ads/{platform}/history` |
| `updateAd` | Mutation | `PUT /ads/{platform}/ads` |

Toda operação também aceita um `profileKey` opcional para agir em nome de um User Profile (perfil de usuário). Todas retornam a resposta REST como JSON, então não aceitam seleção de campos.

<h2 id="list-ad-accounts">
  Listar contas de anúncios
</h2>

Comece por aqui. Use os valores de `accountId` da resposta sempre que uma operação pedir `accountId`.

```graphql theme={"system"}
query {
  adAccounts(platform: FACEBOOK, limit: 10)
}
```

<h2 id="search-targeting-options">
  Buscar opções de segmentação
</h2>

`kind` define a busca: `INTERESTS` para segmentação de público, `REGIONS` ou `CITIES` para localizações. Cada tipo aceita apenas seus próprios argumentos. Por exemplo, `countryCode` e `regionId` funcionam apenas com `CITIES`, e `INTERESTS` exige `search`.

```graphql theme={"system"}
query {
  adTargetingSearch(platform: INSTAGRAM, kind: INTERESTS, search: "running")
}
```

```graphql theme={"system"}
query {
  adTargetingSearch(platform: FACEBOOK, kind: CITIES, search: "Austin", countryCode: "US")
}
```

<h2 id="list-ads">
  Listar anúncios
</h2>

Informe pelo menos um entre `campaignId`, `accountId`, `adId`, `postId` ou `socialPostId`. `socialPostId` é o id da publicação na própria rede, para publicações que não foram feitas via Ayrshare.

```graphql theme={"system"}
query {
  ads(platform: FACEBOOK, accountId: "act_1234567890")
}
```

<h2 id="see-what-an-ad-has-cost">
  Ver quanto um anúncio custou
</h2>

```graphql theme={"system"}
query {
  adHistory(platform: FACEBOOK, startDate: "2026-09-01", endDate: "2026-09-30")
}
```

<h2 id="pause-or-resume-an-ad">
  Pausar ou retomar um anúncio
</h2>

`updateAd` altera o gasto real com anúncios. `PAUSED` interrompe o gasto, `ACTIVE` o retoma, e `DELETED` ou `ARCHIVED` encerra o anúncio. O mesmo status também é aplicado ao conjunto de anúncios e à campanha do anúncio, então quaisquer outros anúncios nesse conjunto de anúncios ou campanha mudam junto.

```graphql theme={"system"}
mutation {
  updateAd(platform: FACEBOOK, adId: "120210000000000000", status: PAUSED)
}
```

<Note>
  Em breve será possível impulsionar uma publicação por meio dessas operações. Até lá, use `boostFacebookPost` ou `instagramBoostPost`, ou o endpoint REST de impulsionamento para [Facebook](/docs/apis/ads/facebook/boost-post) ou [Instagram](/docs/apis/ads/instagram/boost-post).
</Note>

As operações por plataforma, como `facebookAdAccounts` e `instagramAds`, continuam funcionando e não foram alteradas.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.