Execute campaign

Deprecated. This page documents the v2 buyer API, which is closed to new API clients and switches off on 1 December 2026. Use V3 instead: see Move a v2 buyer REST integration to V3. The conversion endpoint, Log event, stays open.

POST /api/v2/buyer/campaigns/:id/execute Executes any DRAFT media buys on the campaign, submitting them to ADCP. On a freshly-created campaign the call transitions DRAFT → ACTIVE. You can also call it on an ACTIVE or PAUSED campaign to execute newly-added media buys without affecting the rest of the campaign.

execute submits DRAFT media buys to ADCP. It does not resume a PAUSED campaign — reactivate is the only way to do that. They are different endpoints. COMPLETED, ARCHIVED, and CANCELLED campaigns cannot be executed.

Request

curl -X POST https://api.apostra.com/api/v2/buyer/campaigns/cmp_987654321/execute \
  -H "Authorization: Bearer $SCOPE3_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "debug": false }'

{
  "debug": false
}

Parameters

Field	Type	Required	Notes
`id`	string	Yes	Campaign ID (path parameter). Must be in `DRAFT`, `ACTIVE`, or `PAUSED` status. `COMPLETED`, `ARCHIVED`, and `CANCELLED` campaigns cannot be executed.
`debug`	boolean	No	Defaults to `false`. When `true`, surfaces the raw ADCP request/response and A2A debug logs in each error entry.

Response

{
  "campaignId": "cmp_987654321",
  "success": true,
  "previousStatus": "DRAFT",
  "newStatus": "ACTIVE",
  "mediaBuysAttempted": 2,
  "mediaBuysSucceeded": 2,
  "mediaBuysFailed": 0,
  "mediaBuysExecuted": 2
}

When individual media buy submissions fail, success is false and errors[] carries one entry per failure:

{
  "campaignId": "cmp_987654321",
  "success": false,
  "previousStatus": "DRAFT",
  "newStatus": "DRAFT",
  "mediaBuysAttempted": 1,
  "mediaBuysSucceeded": 0,
  "mediaBuysFailed": 1,
  "mediaBuysExecuted": 1,
  "errors": [
    {
      "mediaBuyId": "mb_abc123",
      "salesAgentId": "agent_xyz",
      "message": "Sales agent returned 422: invalid format for product"
    }
  ]
}

previousStatus / newStatus — campaign status before and after the call.
mediaBuysAttempted / mediaBuysSucceeded / mediaBuysFailed — separate execution outcomes. mediaBuysExecuted keeps its published meaning and equals mediaBuysAttempted, so it can include failed attempts. Use mediaBuysSucceeded to identify successful executions.
errors[] — { mediaBuyId, salesAgentId, message } per failed submission. Typed Storefront routes use their stable public Storefront Agent identity. With debug: true, each entry also includes the full ADCP request/response payloads.

Ledger error after dispatch

If posting the campaign’s committed-spend ledger entry fails after the dispatch drain, the error keeps its original code and cause. Its message confirms that the campaign state was persisted and that media buys already marked SENT were dispatched. Retry execute to post the accounting entry again; previously SENT buys are not dispatched again. This does not mean every attempted buy reached a seller. Check the campaign or media buy status for each buy’s current delivery state.

Errors

Code	When
`VALIDATION_ERROR`	`Cannot execute campaign: campaign is in <status> status and cannot be re-executed.` for a `COMPLETED`, `ARCHIVED`, or `CANCELLED` campaign; has no selected products; or the committed-spend ledger entry could not be posted after the dispatch drain.
`INTERNAL_ERROR`	The committed-spend ledger entry could not be posted after the dispatch drain. The response states what persisted and which `SENT` buys were dispatched.
`NOT_FOUND`	Campaign ID does not exist for the authenticated account.

See Errors for the full error shape and recovery semantics.

Pause campaign

Halt spend across all media buys

Reactivate campaign

Resume a PAUSED campaign back to ACTIVE

Media buy status

Poll live ADCP status after execute

Campaign overview

The campaign object and lifecycle

Start building

Core Concepts

Buyer operations

Seller operations

Cross-Cutting Reference

Buyer API reference

Seller API reference

Release Notes

Execute campaign

Request

Parameters

Response

Ledger error after dispatch

Errors

Pause campaign

Reactivate campaign

Media buy status

Campaign overview

​Request

​Parameters

​Response

​Ledger error after dispatch

​Errors

​Related

Pause campaign

Reactivate campaign

Media buy status

Campaign overview

Request

Parameters

Response

Ledger error after dispatch

Errors

Related