> ## 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 campaigns with optional filtering by advertiser and status. ## OpenAPI ````yaml /v2/buyer-api-v2.yaml get /campaigns openapi: 3.0.0 info: title: Scope3 Buyer API version: 2.0.0 description: |- REST API for advertisers to manage advertisers, campaigns, and reporting. ## Authentication All endpoints require a Bearer token in the Authorization header: ``` Authorization: Bearer your-api-key ``` ## Base URL `https://api.interchange.io/api/v2/buyer` ## For AI Agents AI agents can use the MCP endpoint at `/mcp/v2/buyer` with three tools: - `initialize`: Start an MCP session - `api_call`: Make REST API calls - `ask_about_capability`: Learn about API features servers: - url: https://api.interchange.io/api/v2/buyer description: Production server security: [] tags: - name: Signup description: Request reviewed access to Interchange - name: Account description: Account management, service tokens, and preferences - name: Asks description: >- What you are waiting on Scope3 for — support, product, and supply asks in one list - name: Advertisers description: Manage advertisers - name: Product Discovery description: Discover and select products - name: Campaigns description: Manage advertising campaigns - name: Creatives description: Build, manage, and sync campaign creatives via AdCP Creative Protocol - name: Reporting description: Access performance metrics - name: Event Sources description: >- Manage event source configurations and log conversion/marketing events for attribution - name: Property Lists description: Validate property lists against AAO registry - name: Sales Agents description: View and connect sales agents - name: Measurement description: Measurement sources, records, context, and freshness - name: Syndication description: Syndicate resources to ADCP agents - name: Tasks description: Track async operation status - name: Buyer Billing description: >- Consolidated invoicing for buyers — invoices and pending invoice items issued by Scope3 across the buyer customer. - name: MCP description: Model Context Protocol endpoints for AI agents paths: /campaigns: get: tags: - Campaigns summary: List campaigns description: List campaigns with optional filtering by advertiser and status. operationId: listCampaigns parameters: - in: query name: advertiserId schema: description: Filter by advertiser ID example: '12345' type: string pattern: ^\d+$ description: Filter by advertiser ID - in: query name: name schema: description: Filter by campaign name (case-insensitive, partial match) example: Summer type: string description: Filter by campaign name (case-insensitive, partial match) - in: query name: status schema: description: >- 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"). example: ACTIVE anyOf: - type: array items: $ref: '#/components/schemas/CampaignStatusListFilter' - allOf: - $ref: '#/components/schemas/CampaignStatusListFilter' description: >- 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"). - in: query name: mode schema: description: >- Filter by campaign mode. Accepts a single mode (`?mode=directed`) or repeated values (`?mode=discovery&mode=performance`). example: directed anyOf: - type: array items: $ref: '#/components/schemas/CampaignMode' - allOf: - $ref: '#/components/schemas/CampaignMode' description: >- Filter by campaign mode. Accepts a single mode (`?mode=directed`) or repeated values (`?mode=discovery&mode=performance`). - in: query name: management schema: description: >- 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. example: managed default: all allOf: - $ref: '#/components/schemas/CampaignManagementFilter' description: >- 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. - in: query name: mediaBuyStatus schema: description: >- Filter to only campaigns that have at least one media buy matching any of the given statuses anyOf: - type: array items: type: string enum: - DRAFT - PENDING_APPROVAL - INPUT_REQUIRED - ACTIVE - PAUSED - COMPLETED - CANCELED - FAILED - REJECTED - ARCHIVED - type: string enum: - DRAFT - PENDING_APPROVAL - INPUT_REQUIRED - ACTIVE - PAUSED - COMPLETED - CANCELED - FAILED - REJECTED - ARCHIVED description: >- Filter to only campaigns that have at least one media buy matching any of the given statuses - in: query name: includeArchived schema: description: >- Include archived (soft-deleted) campaigns in the response (default: false). Implicitly treated as true when the status filter contains 'ARCHIVED'. type: string enum: - 'true' - 'false' description: >- Include archived (soft-deleted) campaigns in the response (default: false). Implicitly treated as true when the status filter contains 'ARCHIVED'. - in: query name: fields schema: description: >- Optional response enrichment fields. Pass geo_metro_names to include display labels for geo_metros from the local label table. example: geo_metro_names anyOf: - type: string - type: array items: type: string description: >- Optional response enrichment fields. Pass geo_metro_names to include display labels for geo_metros from the local label table. - in: query name: cursor schema: description: >- 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= type: string description: >- Opaque pagination cursor returned by the previous response. When provided, skip is derived from the cursor and any explicit skip param is ignored. - in: query name: take schema: description: Number of results to return (max 250) example: 50 default: 50 type: integer maximum: 250 minimum: 1 description: Number of results to return (max 250) - in: query name: skip schema: description: Number of results to skip for pagination example: 0 default: 0 type: integer minimum: 0 maximum: 9007199254740991 description: Number of results to skip for pagination responses: '200': description: List campaigns content: application/json: schema: $ref: '#/components/schemas/CampaignListResponse' '400': description: Bad request content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' security: - bearerAuth: [] components: schemas: CampaignStatusListFilter: description: >- 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. type: string enum: - DRAFT - ACTIVE - PAUSED - COMPLETED - CANCELED - ARCHIVED - ALL CampaignMode: description: >- 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). type: string enum: - discovery - performance - directed CampaignManagementFilter: description: >- Management states to include in the list: "tracked", "managed", or "all" (both — the default). type: string enum: - tracked - managed - all CampaignListResponse: description: Response containing a paginated list of campaign summaries type: object properties: campaigns: description: >- Campaigns matching the query, projected to the summary shape. Use `get_campaign` for full detail. type: array items: $ref: '#/components/schemas/CampaignSummary' total: description: Total count of campaigns matching the query example: 42 type: integer minimum: 0 maximum: 9007199254740991 items: description: >- V3 projection of campaign list items. Parallel to campaigns[] for backward compatibility. type: array items: type: object properties: campaign: type: object properties: campaignId: type: string name: type: string handling: type: string enum: - tracking - managing phase: type: string enum: - draft - active - completed - canceled isPaused: type: boolean isArchived: type: boolean autonomy: type: object properties: inventorySelection: type: object properties: mode: type: string enum: - manual - propose - automatic source: type: string enum: - inherited - overridden required: - mode - source additionalProperties: false rebriefing: type: object properties: mode: type: string enum: - manual - propose - automatic source: type: string enum: - inherited - overridden required: - mode - source additionalProperties: false required: - inventorySelection - rebriefing additionalProperties: false source: type: object properties: kind: type: string enum: - interchange - connected_account - adcp sellerId: type: string freshness: type: string enum: - live - stale - error lastSyncedAt: type: string required: - kind additionalProperties: false createdAt: type: string updatedAt: type: string required: - campaignId - name - handling - phase - isPaused - isArchived - createdAt - updatedAt additionalProperties: false advertiser: type: object properties: advertiserId: type: string name: type: string required: - advertiserId - name additionalProperties: false flight: type: object properties: startAt: type: string endAt: type: string progress: type: number required: - startAt - endAt additionalProperties: false market: type: string financials: type: object properties: budget: oneOf: - type: object properties: state: type: string enum: - available value: type: object properties: total: type: number currency: type: string required: - total - currency additionalProperties: false asOf: type: string source: type: string required: - state - value - source additionalProperties: false - type: object properties: state: type: string enum: - pending reason: type: string retryAfterMs: type: number required: - state - reason additionalProperties: false - type: object properties: state: type: string enum: - unavailable reason: type: string required: - state - reason additionalProperties: false - type: object properties: state: type: string enum: - stale value: type: object properties: total: type: number currency: type: string required: - total - currency additionalProperties: false asOf: type: string source: type: string reason: type: string required: - state - value - asOf - source - reason additionalProperties: false type: object spend: oneOf: - type: object properties: state: type: string enum: - available value: type: object properties: total: type: number currency: type: string required: - total - currency additionalProperties: false asOf: type: string source: type: string required: - state - value - source additionalProperties: false - type: object properties: state: type: string enum: - pending reason: type: string retryAfterMs: type: number required: - state - reason additionalProperties: false - type: object properties: state: type: string enum: - unavailable reason: type: string required: - state - reason additionalProperties: false - type: object properties: state: type: string enum: - stale value: type: object properties: total: type: number currency: type: string required: - total - currency additionalProperties: false asOf: type: string source: type: string reason: type: string required: - state - value - asOf - source - reason additionalProperties: false type: object pacing: oneOf: - type: object properties: state: type: string enum: - available value: type: object properties: percent: type: number verdict: type: string enum: - behind - on_track - ahead required: - percent - verdict additionalProperties: false asOf: type: string source: type: string required: - state - value - source additionalProperties: false - type: object properties: state: type: string enum: - pending reason: type: string retryAfterMs: type: number required: - state - reason additionalProperties: false - type: object properties: state: type: string enum: - unavailable reason: type: string required: - state - reason additionalProperties: false - type: object properties: state: type: string enum: - stale value: type: object properties: percent: type: number verdict: type: string enum: - behind - on_track - ahead required: - percent - verdict additionalProperties: false asOf: type: string source: type: string reason: type: string required: - state - value - asOf - source - reason additionalProperties: false type: object dailyBudget: oneOf: - type: object properties: state: type: string enum: - available value: type: object properties: total: type: number currency: type: string required: - total - currency additionalProperties: false asOf: type: string source: type: string required: - state - value - source additionalProperties: false - type: object properties: state: type: string enum: - pending reason: type: string retryAfterMs: type: number required: - state - reason additionalProperties: false - type: object properties: state: type: string enum: - unavailable reason: type: string required: - state - reason additionalProperties: false - type: object properties: state: type: string enum: - stale value: type: object properties: total: type: number currency: type: string required: - total - currency additionalProperties: false asOf: type: string source: type: string reason: type: string required: - state - value - asOf - source - reason additionalProperties: false type: object spendToday: oneOf: - type: object properties: state: type: string enum: - available value: type: object properties: total: type: number currency: type: string required: - total - currency additionalProperties: false asOf: type: string source: type: string required: - state - value - source additionalProperties: false - type: object properties: state: type: string enum: - pending reason: type: string retryAfterMs: type: number required: - state - reason additionalProperties: false - type: object properties: state: type: string enum: - unavailable reason: type: string required: - state - reason additionalProperties: false - type: object properties: state: type: string enum: - stale value: type: object properties: total: type: number currency: type: string required: - total - currency additionalProperties: false asOf: type: string source: type: string reason: type: string required: - state - value - asOf - source - reason additionalProperties: false type: object required: - budget - spend - pacing additionalProperties: false outcome: oneOf: - type: object properties: state: type: string enum: - available value: type: object properties: label: type: string actual: type: number target: type: number unit: type: string verdict: type: string enum: - working - off_goal - neutral required: - label - actual - unit - verdict additionalProperties: false asOf: type: string source: type: string required: - state - value - source additionalProperties: false - type: object properties: state: type: string enum: - pending reason: type: string retryAfterMs: type: number required: - state - reason additionalProperties: false - type: object properties: state: type: string enum: - unavailable reason: type: string required: - state - reason additionalProperties: false - type: object properties: state: type: string enum: - stale value: type: object properties: label: type: string actual: type: number target: type: number unit: type: string verdict: type: string enum: - working - off_goal - neutral required: - label - actual - unit - verdict additionalProperties: false asOf: type: string source: type: string reason: type: string required: - state - value - asOf - source - reason additionalProperties: false type: object attention: type: array items: type: string enum: - blocked - off_goal - drifted - stale attentionNote: type: string nextAction: type: object properties: action: type: string label: type: string params: type: object additionalProperties: {} required: - action - label additionalProperties: false required: - campaign - advertiser - financials - outcome - attention additionalProperties: false activeCount: description: >- Count of active (not paused/archived) campaigns across the whole query scope, independent of pagination. Present only for the V3 Campaigns experience. example: 23 type: integer minimum: 0 maximum: 9007199254740991 v3Enabled: description: >- 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. type: boolean nextCursor: description: Opaque cursor for the next page. Absent when there is no next page. type: string hasMore: description: Whether there are more campaigns beyond this page. type: boolean required: - campaigns - total - hasMore additionalProperties: false ErrorResponse: description: Standard error response type: object properties: data: type: string nullable: true enum: - null error: $ref: '#/components/schemas/ApiError' required: - data - error additionalProperties: false CampaignSummary: description: >- Compact campaign view returned by list endpoints. Use `get_campaign` for the full resource. type: object properties: campaignId: description: Unique identifier for the campaign example: cmp_987654321 type: string advertiserId: description: Advertiser ID that owns this campaign example: '12345' type: string name: description: Campaign name example: Summer 2025 Campaign type: string status: description: Current campaign status type: string enum: - DRAFT - ACTIVE - PAUSED - COMPLETED - CANCELED - ARCHIVED mode: description: >- Who is steering this campaign — discovery, performance, or directed. Backfilled by projection for existing campaigns (see deriveCampaignMode); no data movement. The "directed" value is deprecated: read `management` instead. allOf: - $ref: '#/components/schemas/CampaignMode' management: description: >- Whether the platform acts on this campaign: "tracked" (a campaign the platform did not set up, mirrored read-only from a connected seller account) or "managed" (authored or adopted through the platform). allOf: - $ref: '#/components/schemas/CampaignManagement' directed: description: >- Subscription-backed directed mirror state — connection, upstream account, dual-keyed ids, and sync health. Not present on inbound single-storefront AdCP campaigns. allOf: - $ref: '#/components/schemas/DirectedCampaignInfo' flightDates: description: Campaign flight dates type: object properties: startDate: description: Campaign start date (ISO 8601) example: '2025-01-15T00:00:00Z' type: string format: date-time pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$ endDate: description: Campaign end date (ISO 8601) example: '2025-03-31T23:59:59Z' type: string format: date-time pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$ required: - startDate - endDate additionalProperties: false constraints: description: Targeting constraints type: object properties: geo_countries: type: array items: type: string geo_countries_exclude: type: array items: type: string geo_regions: type: array items: type: string geo_regions_exclude: type: array items: type: string geo_metros: type: array items: type: object properties: system: anyOf: - type: string enum: - nielsen_dma - type: string enum: - uk_itl1 - type: string enum: - uk_itl2 - type: string enum: - eurostat_nuts2 - type: string enum: - custom values: type: array items: type: string required: - system - values additionalProperties: {} geo_metros_exclude: type: array items: type: object properties: system: anyOf: - type: string enum: - nielsen_dma - type: string enum: - uk_itl1 - type: string enum: - uk_itl2 - type: string enum: - eurostat_nuts2 - type: string enum: - custom values: type: array items: type: string required: - system - values additionalProperties: {} geo_postal_areas: type: array items: anyOf: - type: object properties: country: type: string pattern: ^[A-Z]{2}$ system: anyOf: - type: string enum: - postal_code - type: string enum: - zip - type: string enum: - zip_plus_four - type: string enum: - outward - type: string enum: - full - type: string enum: - fsa - type: string enum: - plz - type: string enum: - code_postal - type: string enum: - postcode - type: string enum: - cep - type: string enum: - pin - type: string enum: - custom - type: string enum: - us_zip - type: string enum: - us_zip_plus_four - type: string enum: - gb_outward - type: string enum: - gb_full - type: string enum: - ca_fsa - type: string enum: - ca_full - type: string enum: - de_plz - type: string enum: - fr_code_postal - type: string enum: - au_postcode - type: string enum: - ch_plz - type: string enum: - at_plz values: type: array items: type: string required: - country - system - values additionalProperties: {} - type: object properties: system: anyOf: - type: string enum: - us_zip - type: string enum: - us_zip_plus_four - type: string enum: - gb_outward - type: string enum: - gb_full - type: string enum: - ca_fsa - type: string enum: - ca_full - type: string enum: - de_plz - type: string enum: - fr_code_postal - type: string enum: - au_postcode - type: string enum: - ch_plz - type: string enum: - at_plz values: type: array items: type: string required: - system - values additionalProperties: {} geo_postal_areas_exclude: type: array items: anyOf: - type: object properties: country: type: string pattern: ^[A-Z]{2}$ system: anyOf: - type: string enum: - postal_code - type: string enum: - zip - type: string enum: - zip_plus_four - type: string enum: - outward - type: string enum: - full - type: string enum: - fsa - type: string enum: - plz - type: string enum: - code_postal - type: string enum: - postcode - type: string enum: - cep - type: string enum: - pin - type: string enum: - custom - type: string enum: - us_zip - type: string enum: - us_zip_plus_four - type: string enum: - gb_outward - type: string enum: - gb_full - type: string enum: - ca_fsa - type: string enum: - ca_full - type: string enum: - de_plz - type: string enum: - fr_code_postal - type: string enum: - au_postcode - type: string enum: - ch_plz - type: string enum: - at_plz values: type: array items: type: string required: - country - system - values additionalProperties: {} - type: object properties: system: anyOf: - type: string enum: - us_zip - type: string enum: - us_zip_plus_four - type: string enum: - gb_outward - type: string enum: - gb_full - type: string enum: - ca_fsa - type: string enum: - ca_full - type: string enum: - de_plz - type: string enum: - fr_code_postal - type: string enum: - au_postcode - type: string enum: - ch_plz - type: string enum: - at_plz values: type: array items: type: string required: - system - values additionalProperties: {} language: type: array items: type: string device_platform: type: array items: anyOf: - type: string enum: - ios - type: string enum: - android - type: string enum: - windows - type: string enum: - macos - type: string enum: - linux - type: string enum: - chromeos - type: string enum: - tvos - type: string enum: - tizen - type: string enum: - webos - type: string enum: - fire_os - type: string enum: - roku_os - type: string enum: - unknown device_type: type: array items: anyOf: - type: string enum: - desktop - type: string enum: - mobile - type: string enum: - tablet - type: string enum: - ctv - type: string enum: - dooh - type: string enum: - unknown device_type_exclude: type: array items: anyOf: - type: string enum: - desktop - type: string enum: - mobile - type: string enum: - tablet - type: string enum: - ctv - type: string enum: - dooh - type: string enum: - unknown channels: description: Channels to target (e.g., ["ctv", "display"]) type: array items: type: string countries: description: >- Deprecated: use geo_countries. Countries to target (ISO 3166-1 alpha-2 codes). Values are normalized into geo_countries on write. deprecated: true maxItems: 250 type: array items: type: string pattern: ^[A-Z]{2}$ geo_metro_names: description: >- Display labels for included geo_metros codes. Only present when requested with fields=geo_metro_names. allOf: - $ref: '#/components/schemas/CampaignGeoMetroNames' geo_metro_names_exclude: description: >- Display labels for excluded geo_metros_exclude codes. Only present when requested with fields=geo_metro_names. allOf: - $ref: '#/components/schemas/CampaignGeoMetroNames' additionalProperties: {} productCount: description: >- Number of products selected for this campaign. Only present for DRAFT campaigns; after execution, product data is represented through media buys. example: 15 type: integer minimum: 0 maximum: 9007199254740991 createdAt: description: When the campaign was created (ISO 8601) example: '2025-01-15T10:30:00Z' type: string format: date-time pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$ updatedAt: description: When the campaign was last updated (ISO 8601) example: '2025-01-20T14:45:00Z' type: string format: date-time pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$ budget: description: >- Compact budget — total + currency only. Use `get_campaign` for the full budget (dailyCap, pacing) plus allocatedBudget, unallocatedBudget. type: object properties: total: type: number minimum: 0 exclusiveMinimum: true currency: default: USD type: string minLength: 3 maxLength: 3 required: - total - currency additionalProperties: false required: - campaignId - advertiserId - name - status - mode - management - createdAt - updatedAt additionalProperties: false ApiError: description: Structured error object type: object properties: code: description: Machine-readable error code type: string message: description: Human-readable error message type: string field: description: Field path associated with the error type: string details: description: Additional error context type: object additionalProperties: {} required: - code - message additionalProperties: false CampaignManagement: description: >- Whether the platform acts on this campaign. "tracked" = a campaign the platform did not set up, mirrored from a connected seller account: the shell is derived from the buys underneath, read-only, and updates automatically as the seller changes things. "managed" = a campaign authored or adopted through the platform (get_products → create_media_buy → update_media_buy) — the platform sends instructions down. In both states the execution system remains the source of truth. type: string enum: - tracked - managed DirectedCampaignInfo: description: >- Directed campaign provenance. Connected-account campaigns expose mirror health; storefront-endpoint campaigns expose the addressed storefront and dual-key identity. oneOf: - $ref: '#/components/schemas/ConnectedAccountDirectedCampaignInfo' - $ref: '#/components/schemas/StorefrontEndpointDirectedCampaignInfo' type: object discriminator: propertyName: provenance mapping: connected_account: $ref: '#/components/schemas/ConnectedAccountDirectedCampaignInfo' storefront_endpoint: $ref: '#/components/schemas/StorefrontEndpointDirectedCampaignInfo' CampaignGeoMetroNames: description: >- Display labels for metro codes. Returned only when requested with fields=geo_metro_names; labels are derived from the local geo-metro label table and are not accepted on create/update. type: array items: type: object properties: system: description: >- Metro targeting system these display labels belong to, e.g. nielsen_dma. type: string minLength: 1 values: maxItems: 250 type: array items: type: object properties: code: description: Metro code from the corresponding metro targeting field. type: string minLength: 1 name: description: Human-readable display label for the metro code. type: string minLength: 1 required: - code - name additionalProperties: false required: - system - values additionalProperties: false ConnectedAccountDirectedCampaignInfo: description: >- Subscription-backed directed campaign mirror state — connection, upstream account, dual-keyed identifiers, and sync health. type: object properties: provenance: description: >- This directed campaign is mirrored from or authored through a connected seller account. type: string enum: - connected_account connectionId: description: >- The subscribed provider connection this directed campaign is mirrored from. example: conn_abc123 type: string minLength: 1 accountId: description: The connection's upstream account id. example: act_998877 type: string minLength: 1 provider: description: >- Adapter/provider key the connection resolves to, e.g. "tiktok", "pinterest", "talpa". example: tiktok type: string minLength: 1 storefrontId: description: >- Storefront DB id backing this connection, when the provider is modeled as an AdCP storefront. example: 42 type: integer maximum: 9007199254740991 minimum: 1 upstreamMediaBuyId: description: >- The seller's own identifier for the mirrored media buy/campaign — dual-keyed alongside our internal mediaBuyId, per the parity rule (a directed campaign IS a media buy). example: tt_campaign_44521 type: string minLength: 1 mediaBuyId: description: >- Our internal media buy id correlating to the upstream object, once the mirror row exists. type: string subscribed: description: >- Whether the connected account is actively subscribed for periodic metadata mirroring. Alpha usage is dark-metered and not billed. type: boolean mirrorState: description: >- live = mirror is current; stale = last sync failed or is overdue; error = the provider reported an error. type: string enum: - live - stale - error lastSyncedAt: description: >- When the mirror was last refreshed from the upstream platform (ISO 8601). type: string format: date-time pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$ required: - provenance - connectionId - accountId - provider - upstreamMediaBuyId - subscribed - mirrorState additionalProperties: false StorefrontEndpointDirectedCampaignInfo: description: >- Provenance and dual-key identity for a direct buy through one storefront AdCP endpoint. type: object properties: provenance: description: >- This directed campaign was created by an external AdCP buyer addressing one storefront endpoint. type: string enum: - storefront_endpoint storefrontId: description: Storefront DB id that owns execution for this campaign. example: 42 type: integer maximum: 9007199254740991 minimum: 1 buyerMediaBuyId: description: >- AdCP media-buy id used by the external buyer at the storefront boundary. example: buyer_mb_44521 type: string minLength: 1 mediaBuyId: description: >- Interchange media-buy id used by the campaign, contract, reporting, and ledger layers. Omitted only for legacy endpoint shells created before this projection was recorded. example: mb_ETBn4gJ9Wu type: string minLength: 1 required: - provenance - storefrontId - buyerMediaBuyId additionalProperties: false securitySchemes: bearerAuth: type: http scheme: bearer description: API key or access token ````