List campaigns

curl --request GET \
  --url https://api.interchange.io/api/v2/buyer/campaigns \
  --header 'Authorization: Bearer <token>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.interchange.io/api/v2/buyer/campaigns', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "campaigns": [
    {
      "campaignId": "cmp_987654321",
      "advertiserId": "12345",
      "name": "Summer 2025 Campaign",
      "createdAt": "2025-01-15T10:30:00Z",
      "updatedAt": "2025-01-20T14:45:00Z",
      "directed": {
        "provenance": "connected_account",
        "connectionId": "conn_abc123",
        "accountId": "act_998877",
        "provider": "tiktok",
        "upstreamMediaBuyId": "tt_campaign_44521",
        "subscribed": true,
        "storefrontId": 42,
        "mediaBuyId": "<string>",
        "lastSyncedAt": "2023-11-07T05:31:56Z"
      },
      "flightDates": {
        "startDate": "2025-01-15T00:00:00Z",
        "endDate": "2025-03-31T23:59:59Z"
      },
      "constraints": {
        "geo_countries": [
          "<string>"
        ],
        "geo_countries_exclude": [
          "<string>"
        ],
        "geo_regions": [
          "<string>"
        ],
        "geo_regions_exclude": [
          "<string>"
        ],
        "geo_metros": [
          {
            "system": "nielsen_dma",
            "values": [
              "<string>"
            ]
          }
        ],
        "geo_metros_exclude": [
          {
            "system": "nielsen_dma",
            "values": [
              "<string>"
            ]
          }
        ],
        "geo_postal_areas": [
          {
            "country": "<string>",
            "system": "postal_code",
            "values": [
              "<string>"
            ]
          }
        ],
        "geo_postal_areas_exclude": [
          {
            "country": "<string>",
            "system": "postal_code",
            "values": [
              "<string>"
            ]
          }
        ],
        "language": [
          "<string>"
        ],
        "device_platform": [
          "ios"
        ],
        "device_type": [
          "desktop"
        ],
        "device_type_exclude": [
          "desktop"
        ],
        "channels": [
          "<string>"
        ],
        "countries": [
          "<string>"
        ],
        "geo_metro_names": [
          {
            "system": "<string>",
            "values": [
              {
                "code": "<string>",
                "name": "<string>"
              }
            ]
          }
        ],
        "geo_metro_names_exclude": [
          {
            "system": "<string>",
            "values": [
              {
                "code": "<string>",
                "name": "<string>"
              }
            ]
          }
        ]
      },
      "productCount": 15,
      "budget": {
        "total": 1,
        "currency": "USD"
      }
    }
  ],
  "total": 42,
  "hasMore": true,
  "items": [
    {
      "campaign": {
        "campaignId": "<string>",
        "name": "<string>",
        "isPaused": true,
        "isArchived": true,
        "createdAt": "<string>",
        "updatedAt": "<string>",
        "autonomy": {
          "inventorySelection": {},
          "rebriefing": {}
        },
        "source": {
          "sellerId": "<string>",
          "lastSyncedAt": "<string>"
        }
      },
      "advertiser": {
        "advertiserId": "<string>",
        "name": "<string>"
      },
      "financials": {
        "budget": {
          "state": "available",
          "value": {
            "total": 123,
            "currency": "<string>"
          },
          "source": "<string>",
          "asOf": "<string>"
        },
        "spend": {
          "state": "available",
          "value": {
            "total": 123,
            "currency": "<string>"
          },
          "source": "<string>",
          "asOf": "<string>"
        },
        "pacing": {
          "state": "available",
          "value": {
            "percent": 123
          },
          "source": "<string>",
          "asOf": "<string>"
        },
        "dailyBudget": {
          "state": "available",
          "value": {
            "total": 123,
            "currency": "<string>"
          },
          "source": "<string>",
          "asOf": "<string>"
        },
        "spendToday": {
          "state": "available",
          "value": {
            "total": 123,
            "currency": "<string>"
          },
          "source": "<string>",
          "asOf": "<string>"
        }
      },
      "outcome": {
        "state": "available",
        "value": {
          "label": "<string>",
          "actual": 123,
          "unit": "<string>",
          "target": 123
        },
        "source": "<string>",
        "asOf": "<string>"
      },
      "attention": [],
      "flight": {
        "startAt": "<string>",
        "endAt": "<string>",
        "progress": 123
      },
      "market": "<string>",
      "attentionNote": "<string>",
      "nextAction": {
        "action": "<string>",
        "label": "<string>",
        "params": {}
      }
    }
  ],
  "activeCount": 23,
  "v3Enabled": true,
  "nextCursor": "<string>"
}

{
  "data": null,
  "error": {
    "code": "<string>",
    "message": "<string>",
    "field": "<string>",
    "details": {}
  }
}

{
  "data": null,
  "error": {
    "code": "<string>",
    "message": "<string>",
    "field": "<string>",
    "details": {}
  }
}

{
  "data": null,
  "error": {
    "code": "<string>",
    "message": "<string>",
    "field": "<string>",
    "details": {}
  }
}

GET

campaigns

List campaigns

curl --request GET \
  --url https://api.interchange.io/api/v2/buyer/campaigns \
  --header 'Authorization: Bearer <token>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.interchange.io/api/v2/buyer/campaigns', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "campaigns": [
    {
      "campaignId": "cmp_987654321",
      "advertiserId": "12345",
      "name": "Summer 2025 Campaign",
      "createdAt": "2025-01-15T10:30:00Z",
      "updatedAt": "2025-01-20T14:45:00Z",
      "directed": {
        "provenance": "connected_account",
        "connectionId": "conn_abc123",
        "accountId": "act_998877",
        "provider": "tiktok",
        "upstreamMediaBuyId": "tt_campaign_44521",
        "subscribed": true,
        "storefrontId": 42,
        "mediaBuyId": "<string>",
        "lastSyncedAt": "2023-11-07T05:31:56Z"
      },
      "flightDates": {
        "startDate": "2025-01-15T00:00:00Z",
        "endDate": "2025-03-31T23:59:59Z"
      },
      "constraints": {
        "geo_countries": [
          "<string>"
        ],
        "geo_countries_exclude": [
          "<string>"
        ],
        "geo_regions": [
          "<string>"
        ],
        "geo_regions_exclude": [
          "<string>"
        ],
        "geo_metros": [
          {
            "system": "nielsen_dma",
            "values": [
              "<string>"
            ]
          }
        ],
        "geo_metros_exclude": [
          {
            "system": "nielsen_dma",
            "values": [
              "<string>"
            ]
          }
        ],
        "geo_postal_areas": [
          {
            "country": "<string>",
            "system": "postal_code",
            "values": [
              "<string>"
            ]
          }
        ],
        "geo_postal_areas_exclude": [
          {
            "country": "<string>",
            "system": "postal_code",
            "values": [
              "<string>"
            ]
          }
        ],
        "language": [
          "<string>"
        ],
        "device_platform": [
          "ios"
        ],
        "device_type": [
          "desktop"
        ],
        "device_type_exclude": [
          "desktop"
        ],
        "channels": [
          "<string>"
        ],
        "countries": [
          "<string>"
        ],
        "geo_metro_names": [
          {
            "system": "<string>",
            "values": [
              {
                "code": "<string>",
                "name": "<string>"
              }
            ]
          }
        ],
        "geo_metro_names_exclude": [
          {
            "system": "<string>",
            "values": [
              {
                "code": "<string>",
                "name": "<string>"
              }
            ]
          }
        ]
      },
      "productCount": 15,
      "budget": {
        "total": 1,
        "currency": "USD"
      }
    }
  ],
  "total": 42,
  "hasMore": true,
  "items": [
    {
      "campaign": {
        "campaignId": "<string>",
        "name": "<string>",
        "isPaused": true,
        "isArchived": true,
        "createdAt": "<string>",
        "updatedAt": "<string>",
        "autonomy": {
          "inventorySelection": {},
          "rebriefing": {}
        },
        "source": {
          "sellerId": "<string>",
          "lastSyncedAt": "<string>"
        }
      },
      "advertiser": {
        "advertiserId": "<string>",
        "name": "<string>"
      },
      "financials": {
        "budget": {
          "state": "available",
          "value": {
            "total": 123,
            "currency": "<string>"
          },
          "source": "<string>",
          "asOf": "<string>"
        },
        "spend": {
          "state": "available",
          "value": {
            "total": 123,
            "currency": "<string>"
          },
          "source": "<string>",
          "asOf": "<string>"
        },
        "pacing": {
          "state": "available",
          "value": {
            "percent": 123
          },
          "source": "<string>",
          "asOf": "<string>"
        },
        "dailyBudget": {
          "state": "available",
          "value": {
            "total": 123,
            "currency": "<string>"
          },
          "source": "<string>",
          "asOf": "<string>"
        },
        "spendToday": {
          "state": "available",
          "value": {
            "total": 123,
            "currency": "<string>"
          },
          "source": "<string>",
          "asOf": "<string>"
        }
      },
      "outcome": {
        "state": "available",
        "value": {
          "label": "<string>",
          "actual": 123,
          "unit": "<string>",
          "target": 123
        },
        "source": "<string>",
        "asOf": "<string>"
      },
      "attention": [],
      "flight": {
        "startAt": "<string>",
        "endAt": "<string>",
        "progress": 123
      },
      "market": "<string>",
      "attentionNote": "<string>",
      "nextAction": {
        "action": "<string>",
        "label": "<string>",
        "params": {}
      }
    }
  ],
  "activeCount": 23,
  "v3Enabled": true,
  "nextCursor": "<string>"
}

{
  "data": null,
  "error": {
    "code": "<string>",
    "message": "<string>",
    "field": "<string>",
    "details": {}
  }
}

{
  "data": null,
  "error": {
    "code": "<string>",
    "message": "<string>",
    "field": "<string>",
    "details": {}
  }
}

{
  "data": null,
  "error": {
    "code": "<string>",
    "message": "<string>",
    "field": "<string>",
    "details": {}
  }
}

Authorizations

Authorization

string

header

required

API key or access token

Query Parameters

advertiserId

string

Filter by advertiser ID

Pattern: ^\d+$

Example:

"12345"

name

string

Filter by campaign name (case-insensitive, partial match)

Example:

"Summer"

status

Filter by campaign status. Accepts a single value or repeated values; pass "ALL" to include every status. Defaults to the non-terminal statuses (ACTIVE, DRAFT, PAUSED) — every campaign that could still spend. Completed, canceled, and archived campaigns require an explicit status filter (or "ALL").

Campaign statuses to include in the list, or "ALL" to include every status. Defaults to the non-terminal statuses (ACTIVE, DRAFT, PAUSED) — every campaign that could still spend.

Available options:

DRAFT,

ACTIVE,

PAUSED,

COMPLETED,

CANCELED,

ARCHIVED,

ALL

Example:

"ACTIVE"

mode

Filter by campaign mode. Accepts a single mode (?mode=directed) or repeated values (?mode=discovery&mode=performance).

Who is steering the campaign. "discovery" (brief-driven) and "performance" (objective-driven) are platform-managed. "directed" is a deprecated wire value retained for compatibility: read management instead — a directed campaign is either tracked (mirrored from a seller account we did not set up) or managed (authored through the platform against one storefront).

Available options:

discovery,

performance,

directed

Example:

"directed"

management

enum<string>

default:all

Filter by management state: "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). The default status lens (non-terminal: ACTIVE, DRAFT, PAUSED) is what keeps mirrored history out of the ambient list; browse tracked scale through the connected-account relationship rollup.

Available options:

tracked,

managed,

all

Example:

"managed"

mediaBuyStatus

Filter to only campaigns that have at least one media buy matching any of the given statuses

Available options:

DRAFT,

PENDING_APPROVAL,

INPUT_REQUIRED,

ACTIVE,

PAUSED,

COMPLETED,

CANCELED,

FAILED,

REJECTED,

ARCHIVED

includeArchived

enum<string>

Include archived (soft-deleted) campaigns in the response (default: false). Implicitly treated as true when the status filter contains 'ARCHIVED'.

Available options:

true,

false

fields

Optional response enrichment fields. Pass geo_metro_names to include display labels for geo_metros from the local label table.

Example:

"geo_metro_names"

cursor

string

Opaque pagination cursor returned by the previous response. When provided, skip is derived from the cursor and any explicit skip param is ignored.

Example:

"eyJza2lwIjoxMH0="

take

integer

default:50

Number of results to return (max 250)

Required range: 1 <= x <= 250

Example:

50

skip

integer

default:0

Number of results to skip for pagination

Required range: 0 <= x <= 9007199254740991

Example:

0

Response

List campaigns

Response containing a paginated list of campaign summaries

campaigns

object[]

required

Campaigns matching the query, projected to the summary shape. Use get_campaign for full detail.

Show child attributes

total

integer

required

Total count of campaigns matching the query

Required range: 0 <= x <= 9007199254740991

Example:

42

hasMore

boolean

required

Whether there are more campaigns beyond this page.

items

object[]

V3 projection of campaign list items. Parallel to campaigns[] for backward compatibility.

Show child attributes

activeCount

integer

Count of active (not paused/archived) campaigns across the whole query scope, independent of pagination. Present only for the V3 Campaigns experience.

Required range: 0 <= x <= 9007199254740991

Example:

23

v3Enabled

boolean

Whether the V3 Campaigns experience (enriched list + redesign) is enabled for this caller via the campaigns-v3 flag. The widget renders the V3 redesign only when true.

nextCursor

string

Opaque cursor for the next page. Absent when there is no next page.

⌘I