---
title: campaign_plan_list
description: 'List the Campaign Plans of your organization, with the money figures that you rank them by.'
---

Ask which Campaign Plans your organization has. The agent gets each one with its figures, newest first, and without its Line Items.

> "Which Campaign Plans do we have, and how much of each envelope is placed?"

The agent calls `campaign_plan_list`. You see each Campaign Plan with its status, its dates, its envelope, the sum that its Line Items hold, its number of Line Items and its channels. When the Line Items of a Campaign Plan mix totals and daily rates, the agent tells you that its figures are not comparable. To see the Line Items of one Campaign Plan, the agent then calls [`campaign_plan_get`](/mcp/tools/campaign-plan-get).

[Plan a campaign](/mcp/tools/plan-a-campaign) walks the whole job.

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

### Output

A successful call returns this object in `structuredContent`.

| Field | Type | Always present | Description |
| --- | --- | --- | --- |
| `campaignPlans` | array of object | yes | The Campaign Plans on this page, newest first. `campaign_plan_get` gives the Line Items of one. |
| `campaignPlans[].allocation` | object | yes | The money of the Campaign Plan. AdCrunch calculates it on each read and does not store it. |
| `campaignPlans[].allocation.allocated` | number or null | yes | The sum of the Line Item budgets, in whole units of the currency. `null` when the Line Items with a budget do not share a unit. |
| `campaignPlans[].allocation.comparable` | boolean | yes | `false` when the Line Items with a budget mix totals and daily rates. Then no sum exists: say "not comparable", and do not add the budgets. |
| `campaignPlans[].allocation.unallocated` | number or null | yes | The envelope less the allocated sum. It can be negative. `null` when the envelope is not set, when the Line Items do not share a unit, or when the unit is `daily`. |
| `campaignPlans[].allocation.unit` | one of `total`, `daily` or null | yes | The unit that the Line Items with a budget share. `null` when no Line Item has a budget, or when the Line Items do not share a unit. |
| `campaignPlans[].brandId` | string or null | yes | The Brand that the Campaign Plan is for, `brd_…`, or `null`. |
| `campaignPlans[].channels` | array of (one of `meta`, `tiktok`, `snapchat`, `google_search`, `google_pmax`, `google_display`, `youtube`, `programmatic_display`, `linkedin`, `x`) | yes | Each channel that its Line Items name, once, in the order that the Line Items were written. |
| `campaignPlans[].currency` | string | yes | ISO 4217. Each amount of the Campaign Plan and of its Line Items is in whole units of this currency. It cannot change after a Line Item has a budget. |
| `campaignPlans[].description` | string | yes | One sentence that tells the Campaign Plan apart in a list. |
| `campaignPlans[].endDate` | string or null | yes | The last day of the Campaign Plan, or `null`. With no end date, the Campaign Plan is always on, and the budget of a Line Item with no end date of its own is a daily rate. |
| `campaignPlans[].lineItemCount` | number | yes | How many Line Items the Campaign Plan holds. |
| `campaignPlans[].name` | string | yes | The display name. |
| `campaignPlans[].revision` | number | yes | The revision of the Campaign Plan. It increments when the Campaign Plan changes. Send it as `base_revision` to `campaign_plan_update`, `campaign_plan_delete` or `campaign_plan_approve`. A Line Item has a revision of its own. |
| `campaignPlans[].slug` | string | yes | The slug of the Campaign Plan. Each tool takes it as `campaign_plan_name`. |
| `campaignPlans[].startDate` | string or null | yes | The first day of the Campaign Plan, or `null`. |
| `campaignPlans[].status` | one of `draft`, `approved` | yes | `approved` when a person approved the content at this revision. A real change to the Campaign Plan, or a Line Item that is added or deleted, returns it to `draft`. |
| `campaignPlans[].totalBudget` | number or null | yes | The envelope: the money that you have, in whole units of `currency`. `null` means no declared limit, not zero. |
| `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 `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.

### Example

The arguments:

```json
{
  "limit": 20
}
```

The result, in `structuredContent`:

```json
{
  "campaignPlans": [
    {
      "allocation": {
        "allocated": 2500,
        "comparable": true,
        "unallocated": 2500,
        "unit": "total"
      },
      "brandId": "brd_6a9c33",
      "channels": [
        "meta"
      ],
      "currency": "EUR",
      "description": "The spring sale of Acme, on Meta, in France and Belgium.",
      "endDate": "2026-05-31",
      "lineItemCount": 1,
      "name": "Spring Sale 2026",
      "revision": 3,
      "slug": "spring-sale",
      "startDate": "2026-03-01",
      "status": "approved",
      "totalBudget": 5000
    }
  ]
}
```