> ## 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.

# Anuncios

> Gestiona anuncios impulsados a través de la API GraphQL de Ayrshare con un único conjunto de operaciones que recibe la plataforma de anuncios como argumento.

Las operaciones de anuncios reciben la plataforma de anuncios como argumento, por lo que la misma operación funciona en todas las plataformas de anuncios que admite Ayrshare. Actualmente son `FACEBOOK` e `INSTAGRAM`.

Cada operación llama al [endpoint REST de anuncios](/docs/apis/ads/overview) correspondiente y devuelve su respuesta sin cambios. La autenticación y los límites son los mismos que en REST. Una llamada fallida devuelve un error de GraphQL: `extensions.status` contiene el estado REST y `extensions.code` el código de error de Ayrshare cuando el error REST tiene uno. Consulta [Errores](/docs/apis/graphql/errors). Las operaciones de anuncios requieren el complemento Ads. Sin él, cada llamada devuelve un error con `extensions.status` `403` y `extensions.code` `399`.

<h2 id="operations">
  Operaciones
</h2>

| Operación | Tipo | Endpoint REST |
| - | - | - |
| `adAccounts` | Query | `GET /ads/{platform}/accounts` |
| `adTargetingSearch` | Query | `GET /ads/{platform}/interests`, `/regions` o `/cities` |
| `ads` | Query | `GET /ads/{platform}/ads` |
| `adHistory` | Query | `GET /ads/{platform}/history` |
| `updateAd` | Mutation | `PUT /ads/{platform}/ads` |
| `boostPost` | Mutation | `POST /ads/{platform}/boost` |

Todas las operaciones aceptan también un `profileKey` opcional para actuar sobre un User Profile (perfil de usuario). Todas devuelven la respuesta REST como JSON, por lo que no admiten selección de campos.

<h2 id="list-ad-accounts">
  Listar cuentas publicitarias
</h2>

Empieza por aquí. Usa los valores de `accountId` de la respuesta siempre que una operación pida `accountId`.

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

<h2 id="search-targeting-options">
  Buscar opciones de segmentación
</h2>

`kind` elige la búsqueda: `INTERESTS` para la segmentación de audiencia, `REGIONS` o `CITIES` para ubicaciones. Cada tipo acepta solo sus propios argumentos. Por ejemplo, `countryCode` y `regionId` solo funcionan con `CITIES`, e `INTERESTS` requiere `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 anuncios
</h2>

Pasa al menos uno de `campaignId`, `accountId`, `adId`, `postId` o `socialPostId`. `socialPostId` es el ID propio de la publicación en la red, para publicaciones que no se publicaron a través de Ayrshare.

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

<h2 id="see-what-an-ad-has-cost">
  Ver cuánto ha costado un anuncio
</h2>

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

<h2 id="pause-or-resume-an-ad">
  Pausar o reanudar un anuncio
</h2>

`updateAd` modifica el gasto publicitario real. `PAUSED` detiene el gasto, `ACTIVE` lo reanuda, y `DELETED` o `ARCHIVED` retira el anuncio. El mismo estado se aplica también al conjunto de anuncios y a la campaña del anuncio, por lo que cualquier otro anuncio de ese conjunto de anuncios o campaña cambia con él. Una campaña o un conjunto de anuncios al que se adjuntó el impulso con `attachTo` conserva su propio estado, y el anuncio solo se publica mientras la campaña y el conjunto de anuncios que lo contienen estén activos.

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

<h2 id="boost-a-post">
  Impulsar una publicación
</h2>

`boostPost` gasta dinero real de la cuenta publicitaria. Convierte una publicación publicada en un anuncio.

* Pasa `postId` (el ID de la publicación en Ayrshare) o `socialPostId` (el ID propio de la publicación en la red).
* Obtén `accountId` de `adAccounts`.
* `budget.amount` está en la moneda de la cuenta publicitaria. Omite `budget` solo cuando `attachTo.adSetId` añade el anuncio a un conjunto de anuncios que ya gestionas, que conserva su propio presupuesto. En ese caso, omite también `targeting`: el conjunto de anuncios conserva su propia segmentación. Consulta [Impulsar en una campaña o un conjunto de anuncios existente](/docs/apis/ads/facebook/boost-post#attach-to).
* `schedule`, `targeting`, `callToAction`, `attachTo` y `status` son opcionales. Si omites `status` y `schedule`, el anuncio queda **activo, empieza de inmediato y no tiene fecha de finalización**, por lo que sigue gastando hasta que lo pauses. Establece `status: PAUSED` o `schedule.end` para limitarlo.
* Coloca los ajustes exclusivos de una plataforma en `platformOptions`, con la plataforma como clave. En Facebook e Instagram, `adName` y `bidAmount` son **obligatorios** ahí, por ejemplo `platformOptions: { facebook: { adName: "Autumn sale", bidAmount: 2 } }`. Sin ellos, el impulso devuelve un error de campos faltantes. Con `attachTo.adSetId`, omite `bidAmount`: el conjunto de anuncios conserva su propia puja.

```graphql theme={"system"}
mutation {
  boostPost(
    platform: FACEBOOK
    accountId: "act_1234567890"
    postId: "RNlSOkyxl9G3EDhlPuCK"
    goal: "engagement"
    budget: { amount: 20, type: DAILY }
    schedule: { start: "2026-10-10T09:00:00Z", end: "2026-10-17T09:00:00Z" }
    targeting: { ageMin: 25, ageMax: 45, locations: { countries: ["US"] } }
    platformOptions: { facebook: { adName: "Autumn sale", bidAmount: 2 } }
    idempotencyKey: "4f9c2a7e-1b3d-4c8e-9a6f-2d5b7e0c1a34"
  )
}
```

Algunos argumentos admiten más de una forma, por lo que usan el tipo `JSON`:

* `accountId` acepta una cadena o un número.
* Las fechas de `schedule` aceptan una fecha o fecha y hora ISO 8601, como `"2026-10-10T09:00:00Z"`. Usa esa forma en lugar de un número. `schedule.end` también acepta `0` para indicar que no hay fecha de finalización.
* Las claves de ubicación aceptan un valor o una lista.
* `targeting.interests` acepta IDs como cadenas o números.
* `platformOptions` acepta un objeto.

<Tip>
  Envía un `idempotencyKey` nuevo, como un UUID, con cada impulso. Si una llamada agota el tiempo de espera o falla, reinténtala con la misma clave y los mismos argumentos.

  * Si el primer impulso terminó, el reintento devuelve su respuesta en lugar de crear y pagar un segundo anuncio.
  * Si el primer impulso sigue en curso, el reintento devuelve un error con `extensions.status` `409`. Espera y vuelve a intentarlo con la misma clave. No cambies a una clave nueva.
  * Reutilizar una clave con argumentos distintos también devuelve `409`.
</Tip>

Para detener el gasto del anuncio, llama a `updateAd` con `status: PAUSED`. `boostFacebookPost` e `instagramBoostPost` siguen funcionando.

Las operaciones por plataforma, como `facebookAdAccounts` e `instagramAds`, siguen funcionando y no han cambiado.


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