> ## Documentation Index
> Fetch the complete documentation index at: https://docs.interchange.io/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 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](/v2/buyer/campaigns/directed-campaigns), not the
ambient list.

## Request

```bash theme={null}
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

```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. `total` is the count across all pages.
Results use offset pagination (`take` / `skip`); see
[Pagination](/v2/reference/pagination).

## Errors

* `400 VALIDATION_ERROR` — invalid `status` or `mode` value.

See [Errors](/v2/reference/errors) for the full error contract.

## Related

<CardGroup cols={2}>
  <Card title="Get campaign" href="/v2/buyer/campaigns/tasks/get-campaign" icon="magnifying-glass">
    Full resource for one campaign
  </Card>

  <Card title="Create campaign" href="/v2/buyer/campaigns/tasks/create-campaign" icon="plus">
    Open a new DRAFT campaign
  </Card>

  <Card title="Pagination" href="/v2/reference/pagination" icon="arrow-right-arrow-left">
    Offset-based list paging
  </Card>

  <Card title="Campaign overview" href="/v2/object-guides/campaign" icon="rocket">
    Fields, lifecycle, and concepts
  </Card>
</CardGroup>