campaign_plan_list

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.

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 describes the shape of a failed call.

invalid_cursor
forbidden
invalid_request
internal_error

Scope

The token must hold campaign_plan: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:

{
  "limit": 20
}

The result, in structuredContent:

{
  "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
    }
  ]
}