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

# Ads

> Manage boosted ads through the Ayrshare GraphQL API with one set of operations that takes the ads platform as an argument.

The ads operations take the ads platform as an argument, so the same operation works on every ads platform Ayrshare supports. Today that is `FACEBOOK` and `INSTAGRAM`.

Each operation calls the matching [REST ads endpoint](/docs/apis/ads/overview) and returns its response unchanged. Authentication and limits are the same as REST. A failed call returns a GraphQL error: `extensions.status` carries the REST status, and `extensions.code` the Ayrshare error code when the REST error has one. See [Errors](/docs/apis/graphql/errors). Ads operations need the Ads add-on. Without it, every call returns an error with `extensions.status` `403` and `extensions.code` `399`.

## Operations

| Operation | Type | REST endpoint |
| - | - | - |
| `adAccounts` | Query | `GET /ads/{platform}/accounts` |
| `adTargetingSearch` | Query | `GET /ads/{platform}/interests`, `/regions` or `/cities` |
| `ads` | Query | `GET /ads/{platform}/ads` |
| `adHistory` | Query | `GET /ads/{platform}/history` |
| `updateAd` | Mutation | `PUT /ads/{platform}/ads` |

Every operation also takes an optional `profileKey` to act on a User Profile. All of them return the REST response as JSON, so they take no field selection.

## List ad accounts

Start here. Use the `accountId` values in the response wherever an operation asks for `accountId`.

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

## Search targeting options

`kind` picks the search: `INTERESTS` for audience targeting, `REGIONS` or `CITIES` for locations. Each kind takes only its own arguments. For example, `countryCode` and `regionId` work only with `CITIES`, and `INTERESTS` needs `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")
}
```

## List ads

Pass at least one of `campaignId`, `accountId`, `adId`, `postId` or `socialPostId`. `socialPostId` is the network's own post id, for posts not published through Ayrshare.

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

## See what an ad has cost

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

## Pause or resume an ad

`updateAd` changes real ad spend. `PAUSED` stops spending, `ACTIVE` resumes it, and `DELETED` or `ARCHIVED` retires the ad. The same status is also set on the ad's ad set and campaign, so any other ads in that ad set or campaign change with it.

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

<Note>
  Boosting a post through these operations is coming. Until then, use `boostFacebookPost` or `instagramBoostPost`, or the REST boost endpoint for [Facebook](/docs/apis/ads/facebook/boost-post) or [Instagram](/docs/apis/ads/instagram/boost-post).
</Note>

The per-platform operations, such as `facebookAdAccounts` and `instagramAds`, still work and are unchanged.


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