List campaigns

GET /api/v2/buyer/campaigns Returns campaigns in a compact summary shape — identity, mode, status, flight dates, flattened budget, and product count. Filter by advertiser, status, or mode. Use Get campaign for the full resource.

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`, or `ARCHIVED`. Accepts a single value or repeated values
`mode`	enum	No	Query param — `discovery`, `performance`, or `directed`
`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",
      "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
}

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

Get media buy status Pause campaign

⌘I

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