Skip to main content
GET
List campaigns

Authorizations

​
Authorization
string
header
required

API key or access token

Query Parameters

​
labels
string

Internal V3 label predicate.

​
advertiserId
string

Filter by advertiser ID

Pattern: ^\d+$
Example:

"12345"

​
name
string

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

Example:

"Summer"

​
campaignName
string

Campaigns Page name filter (case-insensitive, partial match)

Example:

"Summer"

​
campaignStatus

Campaigns Page status set.

Available options:
needs_attention,
active,
draft,
completed,
paused,
canceled,
archived
​
campaignMode
enum<string>

Campaigns Page management filter.

Available options:
managed,
tracked
​
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,
ENDING,
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 provider 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 provider 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 provider-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
​
archivedOnly
boolean

Restrict the response to archived campaigns, including legacy ARCHIVED-status rows.

​
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: 0 < 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.

​
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.

​
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 this response includes the V3 enrichment (activeCount, and per-item dailyBudget and spendToday). Buyer reads return true after the Campaigns cutover; seller-advertiser reads always return false, and any read returns false when the feature evaluation is unavailable.

​
nextCursor
string

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

​
defaultStatusFilter
object

Present when the request sent no status and the default status filter left out campaigns that match every other filter. Archived campaigns are counted only when includeArchived or archivedOnly is set, because status=ALL alone does not return them.