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

Lists ad entities of any level under a single advertiser. One generic tool covers every entity type across providers — filter by the provider-native `type` (campaign, adset, ad_group, ad, creative, …) and/or by `parentId` to walk the tree. Use [`list_advertisers`](/mcp/tools/list-advertisers) first to get the `advertiserId`.

## Input

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `advertiserId` | `acc_*` | yes | The advertiser to list under. Must belong to your organization. |
| `type` | `string` | no | Provider-native entity type, e.g. `campaign`, `adset`, `ad_group`, `ad`, `creative`. |
| `parentId` | `string` (`type:id`) | no | Return only direct children of this entity, e.g. `campaign:123`. |
| `status` | `'ACTIVE' \| 'PAUSED' \| 'DELETED' \| 'ARCHIVED'` | no | Filter by normalized status. |
| `ids` | `string[]` | no | Restrict to specific entity IDs. |
| `limit` | `number` (1–500) | no | Page size. |
| `offset` | `number` | no | Page offset. |

## Output

`{ entities: [...] }` — an array of entity metadata rows. Each carries `provider`, `type`, `id` (bare, provider-native), `name`, `status`, `advertiserId`, `parentId` (`type:id`), `path` (the ancestor chain), and `currency` (the account currency, ISO 4217). This is lean metadata; for the full provider-native payload of one entity, use [`get_entity`](/mcp/tools/get-entity).

A campaign and an ad group also carry their budget:

| Field | Description |
| --- | --- |
| `budget` | The entity's own budget, in **whole units** of `currency`: `50` is 50.00. Null when the entity has no budget of its own. |
| `budgetType` | `daily` or `lifetime`. |
| `budgetLevel` | `campaign` when the campaign carries the budget, `ad_group` when each ad group carries its own. |
| `objective` | The campaign's objective, as the provider writes it. Null at Google Ads, which has none. |

:::warning[Two units of money]

`budget` here is in whole units, like `spend` in [`query_insights`](/mcp/tools/query-insights). [`meta_update_budget`](/mcp/tools/meta-update-budget) and Campaign Plans take **integer minor units**: a budget of `50` here is `5000` there, for a dollar or euro account.

:::

:::info[A stored budget can be old]

Meta does not mark a campaign changed when only its budget changes, and AdCrunch does not yet follow a Google Ads budget change. A budget edited in the provider's own interface can therefore be missing here. The REST API's account-scoped listings accept `fresh=true` to read it from the provider.

:::

## Example

> _"List the active campaigns for that advertiser."_

Claude calls `list_entities({ advertiserId: 'acc_123', type: 'campaign', status: 'ACTIVE' })` and reads back the campaigns with their IDs, then can drill into one with `parentId: 'campaign:<id>'`.

:::tip[Provider-native types]

`type` is the provider's own word — Meta uses `adset`, TikTok and Google use `ad_group`. Discover the exact types by listing without a `type` filter first.

:::

## Errors

- `401` or `403` — see [Errors](/mcp/errors), which every tool shares. This one needs `observe:read`.