> ## Documentation Index > Fetch the complete documentation index at: https://docs.apostra.com/llms.txt > Use this file to discover all available pages before exploring further. # List campaigns > List campaign summaries across modes, filterable by advertiser, status, and mode `GET /api/v2/buyer/campaigns` Returns campaigns in a compact summary shape — identity, mode, management state, status, flight dates, flattened budget, and product count. Filter by advertiser, status, mode, or management state. Use [Get campaign](/v2/buyer/campaigns/tasks/get-campaign) for the full resource. The list defaults to the live working set: every non-terminal status (`ACTIVE`, `DRAFT`, `PAUSED`) across both managed campaigns and tracked mirrors from connected provider accounts — connect a provider account and your live spend there is visible immediately. Completed, canceled, and archived campaigns require an explicit `status` filter (or `status=ALL`). A subscribed account may mirror thousands of historical campaigns — browse that scale through the [provider-account rollup](/v2/buyer/campaigns/directed-campaigns), not the ambient list. This endpoint normally requires a Buyer Account. A Seller Account in the [Media Company V3 preview](/v2/features/sandbox#media-company-v3-preview) may use it only with a positive `advertiserId` that has an active own-supply binding to the Seller Account's own Storefront, in either the sandbox or live environment. A live-environment Advertiser additionally requires the Seller Account to be enrolled in `amc-campaign-management`. The response removes any Campaign that is not confined to that Storefront. Campaign detail, mutations, and reporting remain unavailable to the Seller Account through Buyer REST. ## Request ```bash theme={null} curl "https://api.apostra.com/api/v2/buyer/campaigns?advertiserId=12345&status=ACTIVE" \ -H "Authorization: Bearer $SCOPE3_API_KEY" ``` ## Parameters | Field | Type | Required | Notes | | - | - | - | - | | `advertiserId` | string | No | Query param — filter to one advertiser. Required for the Seller compatibility read | | `name` | string | No | Query param — case-insensitive partial match on campaign name | | `status` | enum | No | Query param — `DRAFT`, `ACTIVE`, `PAUSED`, `COMPLETED`, `CANCELED`, `ARCHIVED`, or `ALL` (every status). Accepts a single value or repeated values. Defaults to `ACTIVE` + `DRAFT` + `PAUSED` — every non-terminal campaign | | `mode` | enum | No | Query param — `discovery`, `performance`, or `directed` | | `management` | enum | No | Query param — `tracked` (campaigns the platform did not set up, mirrored from connected provider accounts), `managed` (campaigns authored or adopted through the platform), or `all` (both — the default) | | `mediaBuyStatus` | enum | No | Query param — filter to campaigns that have at least one media buy in any of the given statuses. Accepts a single value or repeated values | | `includeArchived` | boolean | No | Query param — when `true`, include archived campaigns (default `false`). Implicitly `true` when `status=ARCHIVED` | | `fields` | string | No | Pass `geo_metro_names` to include local display labels for `constraints.geo_metros` and `constraints.geo_metros_exclude`. | | `take` | integer | No | Query param — page size | | `skip` | integer | No | Query param — offset for pagination (default 0) | ## Response ```json theme={null} { "campaigns": [ { "campaignId": "cmp_987654321", "advertiserId": "12345", "name": "Q2 2026 Tech Launch", "status": "ACTIVE", "mode": "directed", "management": "tracked", "directed": { "connectionId": "42", "accountId": "tt_advertiser_123", "provider": "tiktok", "upstreamMediaBuyId": "tt_campaign_44521", "mediaBuyId": "mb_abc123", "subscribed": true, "mirrorState": "live", "lastSyncedAt": "2026-07-12T10:15:03.000Z" }, "flightDates": { "startDate": "2026-05-15T00:00:00Z", "endDate": "2026-07-15T23:59:59Z" }, "budget": { "total": 100000, "currency": "USD" }, "productCount": 0, "createdAt": "2026-05-01T09:00:00Z", "updatedAt": "2026-05-15T12:00:00Z" } ], "total": 1 } ``` The tracked row above appears in the default list while it is active or paused; once the seller completes or cancels it upstream, reaching it requires an explicit `status` filter (or `status=ALL`). Each entry is a summary, not the full resource — `mediaBuys`, `audiences`, budget allocation fields, and `creativeFormats` are omitted. `directed` is present only for `mode: "directed"`; use its `mirrorState` and `lastSyncedAt` for metadata freshness, not delivery freshness. `performanceConfig` is present when the campaign has optimization goals, in the same shape as [Get campaign](/v2/buyer/campaigns/tasks/get-campaign), so a list row shows each goal and its target without a second read. `total` is the count across all pages. Results use offset pagination (`take` / `skip`); see [Pagination](/v2/reference/pagination). ### Campaigns the default status filter left out When the request sends no `status` and the default filter leaves out campaigns that match every other filter, the response adds `defaultStatusFilter`. It says how many campaigns were left out, by status, and how to include them: ```json theme={null} { "campaigns": [], "total": 0, "hasMore": false, "defaultStatusFilter": { "statuses": ["ACTIVE", "DRAFT", "PAUSED"], "hiddenCount": 1, "hiddenByStatus": { "COMPLETED": 1 }, "hint": "1 completed campaign was left out by the default status filter (ACTIVE, DRAFT, PAUSED). Pass status=ALL to include it." } } ``` An empty or short page without `defaultStatusFilter` means no campaign was left out because of its status. Archived campaigns are counted only when the request also sets `includeArchived=true`, because `status=ALL` alone does not return them. The field is never present when the request sends `status`. The advertiser summary's campaign count includes completed and canceled campaigns, so it can be higher than the number of campaigns this list returns by default. Use `defaultStatusFilter` to reconcile the two. ## Errors * `400 VALIDATION_ERROR` — invalid `status` or `mode` value. * `403 CUSTOMER_ROLE_DENIED` — the account is neither a Buyer Account nor a Seller Account listing Campaigns for a bound own-supply Advertiser. * `403 OWN_SUPPLY_SCOPE_REQUIRED` — the Seller compatibility request omitted `advertiserId`, that Advertiser has no active own-Storefront binding, or the Advertiser is in the live environment and the Seller Account is not enrolled in `amc-campaign-management`. See [Errors](/v2/reference/errors) for the full error contract. ## Related Full resource for one campaign Open a new DRAFT campaign Offset-based list paging Fields, lifecycle, and concepts This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.