---
title: campaign_plan_list
description: 'List the campaign plans in your organization, with the money figures you would rank them by.'
---

Lists the **Campaign Plans** of your organization, newest first: what you intend to run, on which channels, for how much, over what period.

:::warning[A Campaign Plan is not a provider campaign]

It is AdCrunch's own planning document — written before anything is bought, and possibly executed into several campaigns, or none. For campaigns that exist on Meta or Google, use [`list_entities`](/mcp/tools/list-entities) and [`get_entity`](/mcp/tools/get-entity).

:::

## Input

Plans are always scoped to your active organization.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `limit` | `number` | no | The greatest number of rows in the answer, from 1 to 500. The default is 100. |
| `cursor` | `string` | no | The `nextCursor` of the previous answer. Omit it to get the first page. |

## Output

`{ campaignPlans: [...], nextCursor? }`. When `nextCursor` is present, more plans exist: call `campaign_plan_list` again with `cursor` set to that value.

Each plan comes back as summary facts rather than its contents — the Line Items themselves come from [`campaign_plan_get`](/mcp/tools/campaign-plan-get).

| Field | Description |
| --- | --- |
| `slug` | The stable handle every other tool takes. |
| `name`, `description` | What it is, in a line. |
| `currency` | ISO 4217. Every amount on the plan is in whole units of it. |
| `totalBudget` | The **envelope** — what you have. `null` means no declared constraint, which is not zero. |
| `allocation` | `allocated` (what you have placed), `unallocated` (the remainder), `unit`, and `comparable`. |
| `startDate`, `endDate` | Either may be `null`; a `null` end means always-on. |
| `status` | `draft` or `approved`. |
| `lineItemCount`, `channels` | How many rows, and which channels they touch. |

:::tip[Check `allocation.comparable` before you add anything up]

When it is `false`, the plan's lines do not share a unit — some read as a total for a period, others as a rate per day — so there is no sum to state. Say "not comparable" rather than adding them.

:::

## Errors

- `invalid_cursor` — the `cursor` is not a `nextCursor` of this tool, with the same arguments. Send it with no change, or omit it.

Requires the `campaign_plan:read` scope.

## Reference

List this organization's Campaign Plans with the figures you would rank them by: the envelope, the allocated sum and whether it is comparable, the window, the line count and which channels are touched. The Line Items themselves come from campaign_plan_get. A Campaign Plan is AdCrunch's own planning document — it is **not** a campaign on Meta or Google. For those, use list_entities and get_entity. 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 |
| --- | --- | --- | --- |
| `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`. |

### 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 `campaign_plan: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.