# GET /v1/projects/:projectId/ads/:platform/pending (/docs/api/reference/ads/list-pending)



<Endpoint method="GET" path="/v1/projects/:projectId/ads/{platform}/pending" scope="ads:read" phase="1" />

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 [#path-parameters]

<Parameters
  rows="[
  { name: 'projectId', type: 'string (uuid)', required: true },
  { name: 'platform', type: 'string', required: true, enum: ['meta', 'tiktok', 'apple'] },
]"
/>

## Query parameters [#query-parameters]

<Parameters
  rows="[
  { name: 'status', type: 'string | string[]', description: 'Filter by status.', enum: ['pending', 'approved', 'rejected', 'dispatched', 'dispatch_failed'], default: '`pending`' },
  { name: 'actionType', type: 'string', description: 'Filter by action type.', enum: ['pause_ad', 'pause_adset', 'update_budget', 'push_creative', 'replace_creative', 'prune_creative', 'update_targeting', 'update_schedule'] },
  { name: 'cursor', type: 'string' },
  { name: 'limit', type: 'integer', default: '50' },
]"
/>

## Response [#response]

```json
{
  "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.

## See also [#see-also]

* [`POST …/pending/:id/approve`](/docs/api/reference/ads/approve-pending)
* [`POST …/pending/:id/reject`](/docs/api/reference/ads/approve-pending)
* [Run ads as partner](/docs/api/guides/run-ads-as-partner)
* [Webhooks — `approval.dispatched`, `approval.dispatch_failed`](/docs/api/operational/webhooks)