list_ads

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 shows the full job.

Reference

Available on:

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 describes the shape of a failed call.

invalid_cursor
forbidden
invalid_request
internal_error

Scope

The token must hold observe:read. Auth & scopes 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:

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

The result, in structuredContent:

{
  "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
    }
  ]
}