---
title: list_ads
description: List the ads of your ad accounts at Meta, TikTok and Google Ads, as AdCrunch stores them.
---

Ask which ads run in an ad set, an ad group, a campaign or an ad account. The agent reads the ads that AdCrunch stores.

> List the ads of the "Women 25-44, France" ad set.

The agent lists the ads of that ad set. You see the name and the status of each ad, and the ad set and the campaign that hold it. [Read your accounts](/mcp/tools/read-your-accounts) shows the full job.

## Reference

**Available on:** [![Meta](/providers/meta.svg)](https://docs.adcrunch.dev/connect/providers) [![TikTok](/providers/tiktok.svg)](https://docs.adcrunch.dev/connect/providers) [![Google Ads](/providers/gads.svg)](https://docs.adcrunch.dev/connect/providers)

List the ads of your ad accounts at Meta, TikTok and Google Ads. A Google Ads row has the `type` `ad_group_ad`, the word of Google Ads, and an `id` of the form `{adGroupId}~{adId}`. Send `campaignId` to list the ads of one campaign, and `adGroupId` to list the ads of one ad group. An ad has no budget: its ad group or its campaign carries it. It reads what AdCrunch stored at the last ingestion, not what the provider holds now. To ask the provider now, use meta_list_ads, tiktok_list_ads or gads_list_ad_group_ads. Without `advertiserId`, it lists the ads of each ad account of your organization. Use list_advertisers to find the ids of your ad accounts. The row that AdCrunch stored last comes first. The answer holds at most `limit` rows (default 100, maximum 500). When it carries `nextCursor`, more rows exist: call this tool again with the same arguments and `cursor` set to that value. When it carries no `nextCursor`, you have every row.

### Input

| Argument | Type | Required | Description |
| --- | --- | --- | --- |
| `advertiserId` | string | no | List one ad account, prefixed `acc_`. Omit it to list every ad account of your organization. An ad account that your organization does not own gives an empty list. list_advertisers gives the ids. |
| `ids` | array of string | no | List only these ids. An id is the bare id that the provider gives, the `id` of a row. |
| `provider` | one of `meta`, `tiktok`, `snapchat`, `gads`, `dv360`, `x`, `openai` | no | List the ad accounts of one provider. Omit it to list every provider. |
| `status` | one of `ACTIVE`, `PAUSED`, `DELETED`, `ARCHIVED` | no | List one status, the same for each provider. TikTok `ENABLE` and `DISABLE` are `ACTIVE` and `PAUSED` here. |
| `cursor` | string, at least 1 character | no | The `nextCursor` of the previous page. Omit it to get the first page. Send it with no change, and with the same filters as the request that answered it: a cursor from a different query gets a 400 `invalid_cursor`. Do not build or change a cursor. |
| `limit` | integer, 1 to 500 | no | The greatest number of rows on the page, from 1 to 500. The default is 100. A greater value gets a 400, with `error` of `invalid_request`. Default: `100`. |
| `adGroupId` | string | no | List only what this ad group holds. Send the bare id that the provider gives: the `id` of a row of list_ad_groups, and the `adGroupId` of each row here. |
| `campaignId` | string | no | List only what this campaign holds. Send the bare id that the provider gives: the `id` of a row of list_campaigns, and the `campaignId` of each row here. |

### Output

A successful call returns this object in `structuredContent`.

| Field | Type | Always present | Description |
| --- | --- | --- | --- |
| `ads` | array of object | yes | The ads that match, as AdCrunch stored them. An empty array means that no ad matches, or that your organization does not own the advertiser. |
| `ads[].advertiserId` | string | yes | The advertiser that owns it, prefixed `acc_`. |
| `ads[].createdAt` | number or null | yes | When AdCrunch first stored this row. **Null when the row was read live**: AdCrunch holds no copy of it. `createdAt`, `updatedAt` and `deletedAt` are AdCrunch’s own times, so all three are null together on a live row. |
| `ads[].createdTime` | number or null | yes | When the provider created the entity. This is the provider’s own time, so a live row carries it. Null where the provider reports none. |
| `ads[].currency` | string or null | yes | The account currency, ISO 4217. Every row of one advertiser carries the same one. Null when AdCrunch does not know it yet. |
| `ads[].deletedAt` | number or null | yes | When AdCrunch marked the row deleted. A listing never carries a deleted row, so this is null. |
| `ads[].id` | string | yes | The id the provider gives, with no prefix. It is unique for one provider and one type, and it may legitimately recur across two types or two providers. |
| `ads[].name` | string | yes | The name at the provider. |
| `ads[].path` | string | yes | The ancestors and this entity, ids joined by `/`, oldest first. This is what makes a subtree one string comparison. |
| `ads[].provider` | string | yes | The ad platform: `meta`, `tiktok` or `gads`. Those three are the providers whose entities AdCrunch reads, and https://docs.adcrunch.dev/connect/providers says how deep each one goes. |
| `ads[].status` | one of `ACTIVE`, `PAUSED`, `DELETED`, `ARCHIVED` | yes | The status, normalized across the providers. TikTok `ENABLE` and `DISABLE` read here as `ACTIVE` and `PAUSED`. |
| `ads[].updatedAt` | number or null | yes | When AdCrunch last rewrote this row. Null if it never changed. |
| `ads[].updatedTime` | number or null | yes | When the provider last edited the entity. Null where the provider reports none. |
| `ads[].adGroupId` | string or null | yes | The ad group that holds the ad, as the bare id its provider gives. Null only when the stored path of the row names no ad group. |
| `ads[].campaignId` | string or null | yes | The campaign it belongs to, as the bare id its provider gives. Null only when the stored path of the row names no campaign. |
| `ads[].type` | string | yes | The type the provider uses, kept as the provider writes it: `ad` at Meta and TikTok, and `ad_group_ad` at Google Ads. The resource names the concept, and the row keeps the provider’s own word, because a Meta `adset` and a Google Ads `ad_group` are not the same object. |
| `nextCursor` | string | no | Send this value as `cursor` to get the next page. It is absent on the last page. |

### Failure codes

A failed call has `isError` set, and `structuredContent.error` holds one of these codes. [Errors](/mcp/errors) describes the shape of a failed call.

- `invalid_cursor`
- `forbidden`
- `invalid_request`
- `internal_error`

### Scope

The token must hold `observe:read`. [Auth & scopes](/mcp/auth) lists each scope.

### Annotations

A client reads these hints. A hint that the tool does not declare has the default value of the MCP specification.

- **Read-only.** The tool changes nothing.
- **Closed world.** The tool reads and writes the data of AdCrunch only.

### Example

The arguments:

```json
{
  "adGroupId": "120210000000001",
  "advertiserId": "acc_1203456789012345"
}
```

The result, in `structuredContent`:

```json
{
  "ads": [
    {
      "adGroupId": "120210000000001",
      "advertiserId": "acc_1203456789012345",
      "campaignId": "120210000000000",
      "createdAt": 1789610000000,
      "createdTime": 1789600000000,
      "currency": "EUR",
      "deletedAt": null,
      "id": "120210000000002",
      "name": "Carousel — bestsellers",
      "path": "120210000000000/120210000000001/120210000000002",
      "provider": "meta",
      "status": "ACTIVE",
      "type": "ad",
      "updatedAt": null,
      "updatedTime": 1789900000000
    }
  ]
}
```