list_entities

List ad entities (campaigns, ad sets, ad groups, ads, creatives, …) under one advertiser, filtered by type or parent.

Ask what runs in one ad account: its campaigns, its ad sets or ad groups, and its ads. The agent reads the entities that AdCrunch stores for that ad account.

List the active campaigns in the EU account, with their daily budgets.

The agent lists the active campaigns of that ad account. You see the status, the objective and the budget of each campaign. Read your accounts shows the full job.

Reference

Available on:

List ad entities (campaigns, ad sets, ad groups, line items, insertion orders, asset groups, keywords, ads, creatives, …) under an advertiser. Filter by provider-native type and/or parentId. The entity AdCrunch stored last comes first. A campaign or ad group row carries budget in whole units of its currency (50 is 50.00), the unit of spend in query_insights and the unit meta_update_budget and Campaign Plans take. budgetLevel says whether the budget lives on the campaign or on its ad groups. Use list_advertisers to discover advertiser IDs. 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	yes	Advertiser account ID (format: `acc_<id>`). Must belong to the active organization.
`ids`	array of string	no	Filter to specific entity IDs.
`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`.
`parentId`	string	no	Return only direct children of this entity, addressed as `type:id` (e.g. `campaign:123`, `adset:456`).
`status`	one of `ACTIVE`, `PAUSED`, `DELETED`, `ARCHIVED`	no	Filter by normalized status.
`type`	string	no	Provider-native entity type, e.g. campaign, adset, ad_group, line_item, insertion_order, asset_group, keyword, ad, creative.

Output

A successful call returns this object in structuredContent.

Field	Type	Always present	Description
`entities`	array of object	yes	The entities that match. The entity that AdCrunch stored last comes first. An empty array means that no entity matches, or that the organization does not own the advertiser.
`entities[].createdAt`	number	yes	When AdCrunch first stored it, in milliseconds since the Unix epoch, UTC.
`entities[].deletedAt`	number or null	yes	When AdCrunch marked it deleted, in milliseconds since the Unix epoch, UTC. Null when it is not deleted.
`entities[].updatedAt`	number or null	yes	When AdCrunch last changed it, in milliseconds since the Unix epoch, UTC. Null when it never changed.
`entities[].advertiserId`	string	yes	The advertiser that owns the entity, prefixed `acc_`.
`entities[].budget`	number or null	yes	The budget of the entity itself, in whole units of `currency`: `50` is 50.00. It is the unit of `spend` in query_insights. Null when the entity has no budget of its own, and when AdCrunch does not know the currency of the account yet. Then `budgetLevel` tells where the budget is.
`entities[].budgetLevel`	one of `campaign`, `ad_group` or null	yes	Where the budget of the campaign of the entity is. `campaign` when the campaign has the budget. `ad_group` when each ad set or ad group has its own budget. Null on ads and creatives, and on a TikTok campaign whose payload does not tell.
`entities[].budgetType`	one of `daily`, `lifetime` or null	yes	`daily` for a budget that the provider spends each day. `lifetime` for a budget that it spends over the full life of the entity. Null when `budget` has no value from the provider.
`entities[].createdTime`	number or null	yes	When the provider created the entity, in milliseconds since the Unix epoch, UTC. Null when the provider does not report it.
`entities[].currency`	string or null	yes	The currency of the ad account, ISO 4217: the currency of `budget`. Null when AdCrunch does not know it yet.
`entities[].id`	string	yes	The id that the provider gives the entity, with no prefix. get_entity takes it as `id`.
`entities[].name`	string	yes	The name of the entity at the provider.
`entities[].objective`	string or null	yes	The objective of the campaign, as the provider writes it: Meta `OUTCOME_SALES`, TikTok `TRAFFIC`. Null on each entity that is not a campaign, and on each Google Ads campaign.
`entities[].parentId`	string or null	yes	The parent of the entity, written `type:id`, such as `campaign:120210000000000001`. The `parentId` argument takes this value. Null on a campaign and on a creative.
`entities[].path`	string	yes	The ids of the ancestors and of the entity, joined by `/`, the campaign first.
`entities[].provider`	one of `meta`, `tiktok`, `snapchat`, `gads`, `dv360`, `x`, `openai`	yes	The provider of the entity. AdCrunch stores the entities of `meta`, `tiktok` and `gads`.
`entities[].status`	one of `ACTIVE`, `PAUSED`, `DELETED`, `ARCHIVED`	yes	The status of the entity, the same for each provider. TikTok `ENABLE` and `DISABLE` become `ACTIVE` and `PAUSED`. Google Ads `ENABLED` and `REMOVED` become `ACTIVE` and `DELETED`.
`entities[].type`	string	yes	The type of the entity, as the provider writes it: `campaign`, `adset` at Meta, `adgroup` at TikTok, `ad_group` at Google Ads, `ad`, `creative`. get_entity takes it as `type`.
`entities[].updatedTime`	number or null	yes	When the provider last changed the entity, in milliseconds since the Unix epoch, UTC. Null when the provider does not report it.
`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:

{
  "advertiserId": "acc_1203456789012345",
  "status": "ACTIVE",
  "type": "campaign"
}

The result, in structuredContent:

{
  "entities": [
    {
      "advertiserId": "acc_1203456789012345",
      "budget": 150,
      "budgetLevel": "campaign",
      "budgetType": "daily",
      "createdAt": 1789776280000,
      "createdTime": 1789716600000,
      "currency": "EUR",
      "deletedAt": null,
      "id": "120210000000000002",
      "name": "Retargeting – Cart abandoners",
      "objective": "OUTCOME_SALES",
      "parentId": null,
      "path": "120210000000000002",
      "provider": "meta",
      "status": "ACTIVE",
      "type": "campaign",
      "updatedAt": 1790208302000,
      "updatedTime": 1789891424000
    },
    {
      "advertiserId": "acc_1203456789012345",
      "budget": null,
      "budgetLevel": "ad_group",
      "budgetType": null,
      "createdAt": 1789227600000,
      "createdTime": 1787919127000,
      "currency": "EUR",
      "deletedAt": null,
      "id": "120210000000000001",
      "name": "Q4 Acquisition",
      "objective": "OUTCOME_SALES",
      "parentId": null,
      "path": "120210000000000001",
      "provider": "meta",
      "status": "ACTIVE",
      "type": "campaign",
      "updatedAt": 1790208302000,
      "updatedTime": 1789891424000
    }
  ]
}