--- title: list_entities description: 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](/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 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_`). 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](/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 { "advertiserId": "acc_1203456789012345", "status": "ACTIVE", "type": "campaign" } ``` The result, in `structuredContent`: ```json { "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 } ] } ```