Media buying controls

Compare campaigns and periods

Use Performance reporting for date filters, time zones, weighted ROAS, campaign comparisons, and daily delivery. The report below remains a lifetime view for pacing and controls.

Observe → decide → act → verify

Use GET /api/v1/campaigns/{id}/performance for a compact decision report: attributed spend and outcomes, CTR, CPC, CPM, cost per objective, ROAS, lifetime pacing, freshness, hourly observations, and recent decisions. POST /api/v1/campaigns/{id}/reconcile explicitly collects a fresh Meta snapshot. GET is read-only and never spends money. Results are last-click reported attribution, not proof of incremental revenue. Traffic cost per result uses clicks; signup uses attributed registrations; purchase uses attributed purchases.

The observed_at timestamp records when MarketingRouter collected the response. Upstream spend and conversion delay remains unknown. Never interpret missing values as zero. Hourly history retains the first lifetime-counter observation in each UTC hour, up to the latest 168 observations returned; differences are not authoritative daily reports and attribution corrections can reduce counters.

Change delivery within an approved plan

Read the campaign's control_revision, then submit one command. Each successful command increments this revision. The original budget_cents is the owner's approved lifetime ceiling; effective_budget_cents is the current Meta lifetime budget. A budget command sets a new total lifetime amount, not an additional deposit or daily limit.

POST /api/v1/campaigns/{id}/controls
Authorization: Bearer mr_live_...
Idempotency-Key: budget-review-001
Content-Type: application/json

{
  "action": "budget",
  "expected_revision": 2,
  "budget_cents": 7500,
  "reason": "Reduce the lifetime budget while reviewing conversion quality."
}

Available actions are pause, resume and budget. Pause/resume omit budget_cents. campaigns:write is required; a sandbox key cannot control live campaigns. The same endpoint supports local sandbox simulation with no provider calls.

Budgets may be reduced or restored within the original approved ceiling. They must exceed currently reported spend. Resume and budget increases recheck funding, consent, pixel, schedule, plan integrity and the live launch gate. Neither a reduction nor a pause releases reserved credit: late charges must be settled before funds can be reused. Budget decreases do not require an enabled launch gate. Pausing does not require healthy tracking, funding or unchanged creative.

These commands do not change the audience, ad, destination or schedule. Use campaign revisions and fresh owner approval to increase the ceiling or change those parts. The ceiling remains reserved even after a lower effective budget is set.

Retry without duplicate actions

Keep the same request body and Idempotency-Key after a timeout. While a command is unresolved, further commands are blocked. performance.controls.pending supplies its exact input and retry_key. Retry after the running lease finishes; do not create a fresh command to bypass uncertainty. The safe automatic replay window is 23 hours. Older uncertain commands need operator reconciliation.

An idempotent replay returns the original command result, which can be older than the current campaign. Read GET /api/v1/campaigns/{id} afterward. A revision_conflict means another completed command changed the campaign; observe again before deciding. A terminal failed command permits a corrected command with a fresh key. Owner and agent actions appear in the shared activity and decision history.

Make careful buying decisions

Review tracking quality and delivery problems before changing spend. Keep sparse, delayed or stale results out of scaling decisions. Report recommendations are advisory heuristics: 20 attributed conversions and 72 hours before a cost-target review, and a 0.5% click-rate review after 1,000 impressions. These are editable product assumptions in the implementation, not confidence intervals, Meta learning status, or universal performance benchmarks. They never run changes automatically.

Current boundaries

Each campaign still has one ad group and one approved ad. Creative generation and immutable revisions can prepare new tests, but adding variants into a running ad set, audience exclusions/lookalikes, placement breakdowns, bid controls, automatic budget allocation, final unused-fund settlement and autonomous optimization are not yet exposed. No expert-performance or customer-acquisition guarantee is made. Check capabilities for current service enablement before live use.