GET /v1/projects/:projectId/ads/:platform/pending

GET/v1/projects/:projectId/ads/{platform}/pending

Phase 1stable

Auth: Bearer
Scope: ads:read

Lists pending actions queued by the bucket-mode gate's draft modes. Each row is an optimizer recommendation awaiting partner or customer approval before it dispatches to the platform.

Companion endpoint: GET …/{platform}/pending/count returns just the unread count, no body. Useful for a partner-tool badge.

Path parameters

projectId
string (uuid)required
platform
stringrequired
One of: meta, tiktok, apple

Query parameters

status
string | string[]optionaldefault: `pending`
Filter by status.
One of: pending, approved, rejected, dispatched, dispatch_failed
actionType
stringoptional
Filter by action type.
One of: pause_ad, pause_adset, update_budget, push_creative, replace_creative, prune_creative, update_targeting, update_schedule
cursor
stringoptional
limit
integeroptionaldefault: 50

Response

{
  "items": [
    {
      "pendingId": "pa_01HZX9...",
      "actionType": "update_budget",
      "entityType": "campaign",
      "entityId": "cmp_01HZX9...",
      "entityName": "Q3 prospecting",
      "platform": "meta",
      "currentValue": { "dailyBudgetCents": 5000 },
      "newValue": { "dailyBudgetCents": 7500 },
      "rationale": "Top-performing campaign — propose +50% budget; CPA is $4.20 vs target $7.00.",
      "proposedAction": {
        "detail": { /* full platform-specific payload */ }
      },
      "status": "pending",
      "createdAt": "2026-05-08T14:32:11Z",
      "expiresAt": "2026-05-15T14:32:11Z",
      "dispatchedAt": null,
      "dispatchFailureReason": null
    }
  ],
  "nextCursor": null
}

expiresAt — pending actions auto-reject after 7 days unless approved. The expiry is to keep stale recommendations from dispatching after the underlying paid performance has shifted.

GET /v1/projects/:projectId/ads/:platform/pending

Path parameters

Query parameters

Response

See also

On this page