List campaigns

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 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, not the ambient list. This endpoint normally requires a Buyer Account. A Seller Account in the 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

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

{
  "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, 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.

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:

{
  "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 for the full error contract.

Get campaign

Full resource for one campaign

Create campaign

Open a new DRAFT campaign

Pagination

Offset-based list paging

Campaign overview

Fields, lifecycle, and concepts

Start building

Core Concepts

Buyer operations

Seller operations

Cross-Cutting Reference

Buyer API reference

Seller API reference

Release Notes

Request

Parameters

Response

Campaigns the default status filter left out

Errors

Get campaign

Create campaign

Pagination

Campaign overview

​Request

​Parameters

​Response

​Campaigns the default status filter left out

​Errors

​Related

Get campaign

Create campaign

Pagination

Campaign overview

Request

Parameters

Response

Campaigns the default status filter left out

Errors

Related