campaign_plan_approve

Approve a Campaign Plan and validate each draft Line Item on it.

Ask the agent to approve a Campaign Plan, so that the agent can build its Line Items.

“Approve the spring sale Campaign Plan.”

The agent reads the Campaign Plan, then calls campaign_plan_approve with the revision of the Campaign Plan that it read. So the approval is of the content that you saw. The approval also validates each draft Line Item, also a Line Item that another person still writes. It creates nothing and spends nothing. You see the approved Campaign Plan, and how many Line Items the approval validated. To clear one Line Item only, ask the agent to validate that Line Item with line_item_validate.

Plan a campaign walks the whole job.

Reference

Approve a Campaign Plan, which validates every draft Line Item on it and opens the execution gate — a line cannot be executed until it is validated. This blocks on nothing: unbounded, over-allocated and half-written plans are all approvable, because execution carries its own checks and approval is the human act. It creates nothing and spends nothing. Pass base_revision from campaign_plan_get, so the approval is of the content you read. A line added afterwards starts draft and returns the plan to draft. 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.

Input

Argument	Type	Required	Description
`base_revision`	integer	yes	The revision you last read via campaign_plan_get. Guards against writing over a change somebody else made since.
`campaign_plan_name`	string	yes	The Campaign Plan slug — its stable per-organization handle.

Output

A successful call returns this object in structuredContent.

Field	Type	Always present	Description
`campaignPlan`	object	yes	The Campaign Plan as it is now, with its Line Items in full.
`campaignPlan.allocation`	object	yes	The money of the Campaign Plan. AdCrunch calculates it on each read and does not store it.
`campaignPlan.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.
`campaignPlan.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.
`campaignPlan.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`.
`campaignPlan.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.
`campaignPlan.brandId`	string or null	yes	The Brand that the Campaign Plan is for, `brd_…`, or `null`.
`campaignPlan.createdAt`	number	yes	Milliseconds since the Unix epoch, UTC.
`campaignPlan.createdBy`	string	yes	The user who created the Campaign Plan, `usr_…`.
`campaignPlan.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.
`campaignPlan.description`	string	yes	One sentence that tells the Campaign Plan apart in a list.
`campaignPlan.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.
`campaignPlan.id`	string	yes	The id of the Campaign Plan, `cpl_…`.
`campaignPlan.lineItems`	array of object	yes	Each Line Item of the Campaign Plan, in full.
`campaignPlan.lineItems[].advertiserId`	string or null	yes	The ad account that the Line Item runs through, `acc_…`, or `null`.
`campaignPlan.lineItems[].ageMax`	number or null	yes	The highest age, or `null` for no upper bound.
`campaignPlan.lineItems[].ageMin`	number or null	yes	The lowest age, or `null` for no lower bound.
`campaignPlan.lineItems[].budget`	number or null	yes	The amount in whole units of the currency of the Campaign Plan, or `null` when it is not set. `unit` tells how to read it.
`campaignPlan.lineItems[].campaignPlanId`	string	yes	The id of the Campaign Plan that holds the Line Item, `cpl_…`.
`campaignPlan.lineItems[].channel`	one of `meta`, `tiktok`, `snapchat`, `google_search`, `google_pmax`, `google_display`, `youtube`, `programmatic_display`, `linkedin`, `x`	yes	What the Line Item buys, in planning words. A channel is not a provider.
`campaignPlan.lineItems[].countries`	array of string	yes	ISO 3166-1 alpha-2 codes. An empty list means that the geography is not decided.
`campaignPlan.lineItems[].createdAt`	number	yes	Milliseconds since the Unix epoch, UTC.
`campaignPlan.lineItems[].createdBy`	string	yes	The user who added the Line Item, `usr_…`.
`campaignPlan.lineItems[].effectiveEndDate`	string or null	yes	The end that applies: the end date of the Line Item, else the end date of the Campaign Plan. `null` when neither has one.
`campaignPlan.lineItems[].effectiveStartDate`	string or null	yes	The start that applies: the start date of the Line Item, else the start date of the Campaign Plan. `null` when neither has one.
`campaignPlan.lineItems[].endDate`	string or null	yes	The end date of the Line Item itself, or `null` when the Line Item uses the end date of the Campaign Plan.
`campaignPlan.lineItems[].executable`	boolean	yes	`true` when AdCrunch can create objects for this channel today. It is not a promise that a create succeeds.
`campaignPlan.lineItems[].executions`	array of object	yes	The provider objects that the Line Item created, as `line_item_record_execution` recorded them. The list does not tell whether the Line Item is complete.
`campaignPlan.lineItems[].executions[].advertiserId`	string	yes	The ad account that holds the object, `acc_…`.
`campaignPlan.lineItems[].executions[].createdAt`	number	yes	When AdCrunch recorded the object, in milliseconds since the Unix epoch, UTC.
`campaignPlan.lineItems[].executions[].entityId`	string	yes	The id of the object on the provider, with no prefix. `get_entity` and `list_entities` use the same id.
`campaignPlan.lineItems[].executions[].entityType`	string	yes	The word of the provider for the level of the object, such as `campaign`, `adset` or `ad`.
`campaignPlan.lineItems[].executions[].id`	string	yes	The id of the record, `exe_…`.
`campaignPlan.lineItems[].executions[].mutationWorkflowId`	string or null	yes	The `workflowId` of the change that created the object, or `null` when the record names none.
`campaignPlan.lineItems[].executions[].provider`	one of `meta`, `gads`, `tiktok`, `x`, `openai`, `snapchat`, `dv360`	yes	The provider of the object.
`campaignPlan.lineItems[].gender`	one of `all`, `men`, `women` or null	yes	The gender of the audience, or `null` when it is not decided. `null` executes as `all`.
`campaignPlan.lineItems[].id`	string	yes	The id of the Line Item, `lni_…`.
`campaignPlan.lineItems[].objective`	one of `awareness`, `engagement`, `leads`, `sales`, `traffic`, `app_promotion`	yes	What the Line Item is for.
`campaignPlan.lineItems[].personaId`	string or null	yes	The Persona that explains the audience, `psn_…`, or `null`. The countries, the ages and the gender are what execute.
`campaignPlan.lineItems[].provider`	one of `meta`, `gads`, `tiktok`, `x`, `openai`, `snapchat`, `dv360` or null	yes	The provider that sells the channel, or `null` when AdCrunch has no integration for it.
`campaignPlan.lineItems[].revision`	number	yes	The revision of the Line Item. It increments when the Line Item changes. Send it as `base_revision` to `line_item_update`, `line_item_delete` or `line_item_validate`.
`campaignPlan.lineItems[].startDate`	string or null	yes	The start date of the Line Item itself, or `null` when the Line Item uses the start date of the Campaign Plan.
`campaignPlan.lineItems[].status`	one of `draft`, `validated`	yes	`validated` when a person cleared the Line Item to run, by `line_item_validate` or by the approval of the Campaign Plan. A real change to the Line Item returns it to `draft`.
`campaignPlan.lineItems[].unit`	one of `total`, `daily`	yes	How to read `budget`. `total` when the Line Item has an effective end date: the budget is for the whole period. `daily` when it has none: the budget is for each day.
`campaignPlan.lineItems[].updatedAt`	number or null	yes	When the Line Item last changed, or `null` when it never changed.
`campaignPlan.measurement`	string or null	yes	How the result is judged, or `null`.
`campaignPlan.name`	string	yes	The display name.
`campaignPlan.rationale`	string or null	yes	The argument for the split of the money, or `null`. A reviewer approves it.
`campaignPlan.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.
`campaignPlan.slug`	string	yes	The slug of the Campaign Plan. Each tool takes it as `campaign_plan_name`.
`campaignPlan.startDate`	string or null	yes	The first day of the Campaign Plan, or `null`.
`campaignPlan.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`.
`campaignPlan.totalBudget`	number or null	yes	The envelope: the money that you have, in whole units of `currency`. `null` means no declared limit, not zero.
`campaignPlan.updatedAt`	number or null	yes	When the Campaign Plan last changed, or `null` when it never changed.
`lineItemsValidated`	number	yes	How many draft Line Items the approval validated. Zero when each Line Item was validated before.

Failure codes

A failed call has isError set, and structuredContent.error holds one of these codes. Errors describes the shape of a failed call.

not_found
revision_mismatch
forbidden
invalid_request
internal_error

Scope

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

Writes. The tool can change data.
Destructive. The tool can make a change that you cannot undo. A client can ask you to confirm before it calls the tool.
Not idempotent. A second call with the same arguments can change more.
Closed world. The tool reads and writes the data of AdCrunch only.

Example

The arguments:

{
  "base_revision": 2,
  "campaign_plan_name": "spring-sale"
}

The result, in structuredContent:

{
  "campaignPlan": {
    "allocation": {
      "allocated": 2500,
      "comparable": true,
      "unallocated": 2500,
      "unit": "total"
    },
    "brandId": "brd_6a9c33",
    "createdAt": 1768435200000,
    "createdBy": "usr_5d2b71",
    "currency": "EUR",
    "description": "The spring sale of Acme, on Meta, in France and Belgium.",
    "endDate": "2026-05-31",
    "id": "cpl_4e1a08",
    "lineItems": [
      {
        "advertiserId": "acc_1203456789012345",
        "ageMax": 44,
        "ageMin": 25,
        "budget": 2500,
        "campaignPlanId": "cpl_4e1a08",
        "channel": "meta",
        "countries": [
          "FR",
          "BE"
        ],
        "createdAt": 1768435200000,
        "createdBy": "usr_5d2b71",
        "effectiveEndDate": "2026-05-31",
        "effectiveStartDate": "2026-03-01",
        "endDate": null,
        "executable": true,
        "executions": [],
        "gender": "all",
        "id": "lni_2d9e77",
        "objective": "sales",
        "personaId": "psn_8c4a20",
        "provider": "meta",
        "revision": 2,
        "startDate": null,
        "status": "validated",
        "unit": "total",
        "updatedAt": 1769040000000
      }
    ],
    "measurement": "Revenue in the window, against the spring of 2025.",
    "name": "Spring Sale 2026",
    "rationale": "Meta carries the reach. One Line Item keeps the budget in one place.",
    "revision": 3,
    "slug": "spring-sale",
    "startDate": "2026-03-01",
    "status": "approved",
    "totalBudget": 5000,
    "updatedAt": 1769040000000
  },
  "lineItemsValidated": 1
}