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 seller accounts — connect a seller 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 connected-account rollup, not the ambient list.

Request

curl "https://api.interchange.io/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
`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 seller 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. total is the count across all pages. Results use offset pagination (take / skip); see Pagination.

Errors

400 VALIDATION_ERROR — invalid status or mode value.

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

Getting Started

Advertisers

Campaigns

Product Discovery

Webhooks

Creatives

Signals & Brand

Audiences & Inventory

Measurement & Conversions

Reporting & Activity

Planning & Governance

Connections

Account & Billing

Request

Parameters

Response

Errors

Get campaign

Create campaign

Pagination

Campaign overview

​Request

​Parameters

​Response

​Errors

​Related

Get campaign

Create campaign

Pagination

Campaign overview

Request

Parameters

Response

Errors

Related