Get campaign

GET /api/v2/buyer/campaigns/:id Returns the full mode-specific campaign resource. Platform-managed campaigns include planning fields such as brief, audiences, budget allocation, pacing, performance config, frequency caps, and creative format coverage. A directed campaign instead projects exactly one upstream media buy and includes its connection, provider, dual-keyed identity, mirror state, and metadata sync time.

Request

curl https://api.interchange.io/api/v2/buyer/campaigns/cmp_987654321 \
  -H "Authorization: Bearer $SCOPE3_API_KEY"

Parameters

Field	Type	Required	Notes
`id`	string	Yes	Path parameter — the campaign identifier
`mediaBuyId`	string	No	Query parameter. Filter the embedded `mediaBuys[]` to only these media buys. Accepts a single value or repeated values. The campaign itself is unchanged; only the nested media buys are narrowed.
`includePropertyLists`	boolean	No	Query parameter. When `true`, embed a `propertyLists` aggregate showing the include/exclude lists applied to this campaign. Defaults to `false`.
`fields`	string	No	Pass `geo_metro_names` to include local display labels for `constraints.geo_metros` and `constraints.geo_metros_exclude`.

Response

{
  "campaign": {
    "campaignId": "cmp_987654321",
    "advertiserId": "12345",
    "name": "Q2 2026 Tech Launch",
    "status": "ACTIVE",
    "mode": "discovery",
    "management": "managed",
    "flightDates": { "startDate": "2026-05-15T00:00:00Z", "endDate": "2026-07-15T23:59:59Z" },
    "budget": { "total": 100000, "currency": "USD", "pacing": "EVEN" },
    "allocatedBudget": 60000,
    "unallocatedBudget": 40000,
    "optimizationApplyMode": "MANUAL",
    "mediaBuyRefs": [
      { "mediaBuyId": "mb_abc123", "status": "ACTIVE" }
    ],
    "mediaBuys": [
      {
        "mediaBuyId": "mb_abc123",
        "name": "Q2 2026 Tech Launch - Example Media",
        "status": "ACTIVE",
        "budget_denomination": "gross",
        "budget_breakdown": {
          "media_budget": 55200,
          "fee_amount": 4800,
          "fee_rate_percent": 8,
          "effective_gross_cpm": 20.11
        },
        "createdAt": "2026-05-01T09:00:00Z",
        "updatedAt": "2026-05-15T12:00:00Z"
      }
    ],
    "creativeFormats": {
      "required": [{ "format_kind": "video_hosted" }, { "format_kind": "image" }],
      "covered": [{ "format_kind": "video_hosted" }],
      "missing": [{ "format_kind": "image" }]
    },
    "createdAt": "2026-05-01T09:00:00Z",
    "updatedAt": "2026-05-15T12:00:00Z"
  }
}

For platform-managed campaigns, campaign.creativeFormats.missing lists formats that still need creatives, and campaign.mediaBuys[] is populated after execution. campaign.mediaBuyRefs[] remains a complete lightweight inventory, including a ref with status: "ARCHIVED" after a buy is archived; archived buys are omitted from the substantive campaign.mediaBuys[] array. A directed campaign has no execute step: its single mediaBuys[] entry is the mirrored upstream campaign, and creative details are not mirrored in Phase 1. After a directed delivery read, its performance snapshot includes windowStart, windowEnd, and lastUpdated; always display the window because the values represent the latest requested range, not lifetime delivery. For a lightweight scan across many campaigns, use List campaigns. Every budget in the response is gross — fee-inclusive, the amount the customer pays. allocatedBudget is the sum of the budgets of every media buy that still holds budget — DRAFT, PENDING_APPROVAL, INPUT_REQUIRED, ACTIVE, PAUSED — plus delivered spend (all-in, at each buy’s locked fee terms) on ended or archived media buys, and unallocatedBudget is budget.total − allocatedBudget; read them directly rather than re-deriving. A DRAFT buy is already counted in allocatedBudget, so raising that buy’s budget has headroom of currentBudget + unallocatedBudget — don’t add its current budget to allocatedBudget again. unallocatedBudget can go negative when delivered spend on ended buys exceeds budget.total. Each media buy carries budget_denomination: "gross" and a read-only budget_breakdown (media_budget, fee_amount, fee_rate_percent, effective_gross_cpm) showing the media/fee split at the fee terms locked when that buy was created. Both fields appear only on buys with locked fee terms — legacy buys created before fee terms were locked carry neither budget_denomination nor budget_breakdown. See Budgets and fees.

Errors

404 NOT_FOUND — no campaign with this ID is visible to the authenticated account.

See Errors for the full error contract.

List campaigns

Compact summaries across campaigns

Update campaign

Change a campaign or its media buys

Get media buy status

Poll live ADCP status

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

Errors

List campaigns

Update campaign

Get media buy status

Campaign overview

​Request

​Parameters

​Response

​Errors

​Related

List campaigns

Update campaign

Get media buy status

Campaign overview

Request

Parameters

Response

Errors

Related