Run Budget Allocation
POST/api/advertising/budget-plans/:plan/allocate
Starts the budget allocator for the plan as a queued background job and returns its tracked job ID immediately. The allocator spreads the remaining daily target across the plan's live, budgeted campaigns (excluding constraints.exclude_campaign_ids), respecting the plan's constraints.
advertising:writeGrant this scope to your token under Settings → Developer → Personal Access Tokens.
Body: dry_run (optional boolean, default true). A dry run only computes the proposed allocation; dry_run: false produces real campaign budget changes. Poll the tracked job for progress and the outcome.
A run is forced to a preview (result dry_run: true, nothing sent, with the reason in notes) when the plan is not active, when the plan is not for the current month, when the plan's allocation_mode is manual, or when an exchange rate is missing for the plan currency or an account currency.
The tracked job's results carry the allocation: ad_budget_plan_id, dry_run, daily_target, current_total, proposed_total, expected_contribution_change (tenant currency), campaigns_considered, infeasible, notes, change_set_ids (one per ad account when budgets were submitted) and lines. Each line: campaign_id, campaign_name, ad_account_id, platform, currency_code, before and after (daily budget in the account's currency), before_in_tenant_currency and after_in_tenant_currency (the same budgets in the tenant currency, for totals across accounts), marginal_before, marginal_after, elasticity, expected_contribution_change, constraints, reason.
Requires the advertising.manage permission.
Available only when the tenant has both the advertising and advertising-manager features enabled; otherwise every route here returns 404.
Request
Responses
- 200
- 401
- 403
- 404
- 422
- 429
OK
Response Headers
Unauthenticated — the bearer token is missing, revoked, expired, or malformed. Never retry automatically; fix the credential. See the Errors guide.
Forbidden — the token lacks a required scope, the endpoint is not available to API tokens, or the user behind the token lacks the permission. A human must adjust the token scopes or user permissions; do not retry.
Not Found
Response Headers
Unprocessable Entity
Response Headers
Rate limited — platform limit is 1,000 requests/min; individual tokens may carry lower limits. Honor the Retry-After header before retrying. See the Rate Limits guide.