> ## 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. # Get campaign > Get detailed information about a specific campaign. ## OpenAPI ````yaml /v2/buyer-api-v2.yaml get /campaigns/{campaignId} 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/{campaignId}: get: tags: - Campaigns summary: Get campaign description: Get detailed information about a specific campaign. operationId: getCampaign parameters: - in: query name: fresh schema: description: >- When true, bypasses the server-side media-buy query cache for this request. Use after a successful lifecycle write when immediate authoritative local readback is required. example: 'true' anyOf: - type: boolean - type: string enum: - 'true' - 'false' description: >- When true, bypasses the server-side media-buy query cache for this request. Use after a successful lifecycle write when immediate authoritative local readback is required. - in: query name: mediaBuyId schema: description: >- Filter the embedded `mediaBuys[]` array to only the media buys with these IDs. Accepts a single ID (`?mediaBuyId=mb_X`) or repeated values (`?mediaBuyId=mb_X&mediaBuyId=mb_Y`). The campaign object itself is unchanged; only the nested media buys are narrowed. Use to drill into specific buys without loading every buy on the campaign (helps when the full tree exceeds an LLM context window). `mediaBuyRefs` still lists every buy on the campaign so callers can discover IDs. example: mb_ETBn4gJ9Wu anyOf: - type: array items: type: string - type: string description: >- Filter the embedded `mediaBuys[]` array to only the media buys with these IDs. Accepts a single ID (`?mediaBuyId=mb_X`) or repeated values (`?mediaBuyId=mb_X&mediaBuyId=mb_Y`). The campaign object itself is unchanged; only the nested media buys are narrowed. Use to drill into specific buys without loading every buy on the campaign (helps when the full tree exceeds an LLM context window). `mediaBuyRefs` still lists every buy on the campaign so callers can discover IDs. - in: query name: includePropertyLists schema: description: >- When true, embed a `propertyLists` aggregate showing the include/exclude lists actually applied to this campaign via its media-buy packages. Defaults to false to keep the response small. To fetch the aggregate without the rest of the campaign, use `GET /campaigns/:campaignId/property-lists`. example: 'true' anyOf: - type: boolean - type: string enum: - 'true' - 'false' description: >- When true, embed a `propertyLists` aggregate showing the include/exclude lists actually applied to this campaign via its media-buy packages. Defaults to false to keep the response small. To fetch the aggregate without the rest of the campaign, use `GET /campaigns/:campaignId/property-lists`. - in: query name: includeProductDetails schema: description: >- When false, strips `formatOptions` from each product in `mediaBuys[].products[]`. Defaults to true (full product details included). Set to false when the goal is to read `packageId` values or other non-product fields and the full product payload would cause response truncation. example: 'false' anyOf: - type: boolean - type: string enum: - 'true' - 'false' description: >- When false, strips `formatOptions` from each product in `mediaBuys[].products[]`. Defaults to true (full product details included). Set to false when the goal is to read `packageId` values or other non-product fields and the full product payload would cause response truncation. - 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: path name: id schema: description: Unique identifier for the campaign example: cmp_987654321 type: string minLength: 1 required: true description: Unique identifier for the campaign responses: '200': description: Get campaign content: application/json: schema: $ref: '#/components/schemas/CampaignResponse' '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: CampaignResponse: description: Response containing a single campaign type: object properties: campaign: $ref: '#/components/schemas/Campaign' warnings: description: >- Non-blocking advisories about the campaign. On create, includes a soft credit-limit warning when the budget already exceeds the org’s available Scope3 credit (the campaign is still created; the hard 402 gate fires at execute). type: array items: type: string required: - campaign 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 Campaign: description: Campaign resource representation 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' mediaBuyRefs: description: >- Lightweight references to every media buy on this campaign (id + status). Surfaced early in the response so LLM callers can enumerate media buy IDs even when the full nested `mediaBuys[]` tail is truncated by a small context window. Use the `mediaBuyId` query param on `get_campaign` to drill into specific buys without loading the full tree. type: array items: $ref: '#/components/schemas/MediaBuyRef' brief: description: Campaign brief type: string 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 budget: description: Campaign budget configuration type: object properties: total: type: number minimum: 0 exclusiveMinimum: true currency: default: USD type: string minLength: 3 maxLength: 3 dailyCap: type: number minimum: 0 exclusiveMinimum: true pacing: type: string enum: - EVEN - ASAP - FRONTLOADED required: - total - currency additionalProperties: false allocatedBudget: description: >- Sum of active media buy budgets (plus performance spend on archived media buys) on this campaign. Only present when the campaign has a budget.total set. Expressed in the campaign budget currency. example: 7500 type: number minimum: 0 unallocatedBudget: description: >- Media budget remaining for new media buys, computed as the media portion of budget.total (after the Scope3 fee) minus allocatedBudget. Only present when the campaign has a budget.total set. Expressed in the campaign budget currency. May be negative if archived performance spend exceeds the media budget. example: 2500 type: number pacingPeriods: description: >- Pacing schedule for the campaign, if configured. In responses, each period includes a resolved budget (computed dollar amount). In weight mode, weights are preserved alongside the resolved budget. allOf: - $ref: '#/components/schemas/PacingPeriodsOutput' 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: {} storefronts: description: >- Storefronts the campaign is pinned to. When set, every product discovery run for this campaign auto-applies the corresponding storefront filter. Each entry includes both the storefront DB `id` and the public `platformId` + `name` so the response is renderable without a follow-up lookup. Absent or empty means the campaign is not pinned to any specific storefronts. type: array items: $ref: '#/components/schemas/CampaignStorefrontRef' performanceConfig: description: Performance configuration (present for performance campaigns) allOf: - $ref: '#/components/schemas/PerformanceConfigOutput' optimizationApplyMode: description: >- Controls whether Scope3 AI model optimizations to media buys are applied automatically or require manual approval. Defaults to the advertiser-level setting if not explicitly set on the campaign. allOf: - $ref: '#/components/schemas/OptimizationApplyMode' catalogId: description: Attached catalog ID example: 42 type: integer maximum: 9007199254740991 minimum: 1 discoveryId: description: >- ID of the discovery session used to select products for this campaign. Only present for DRAFT campaigns; after execution, product data is represented through media buys. example: session_abc123 type: string 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 products: description: >- Products selected for this campaign. Only present for DRAFT campaigns; after execution, product data is represented through media buys. type: array items: type: object properties: productId: description: Unique identifier for the product example: prod_123 type: string required: - productId additionalProperties: false audiences: description: >- Audiences associated with this campaign (both targeted and suppressed) type: array items: type: object properties: audienceId: description: Unique identifier for the audience example: aud_123 type: string name: description: Display name of the audience example: Tech Enthusiasts 25-34 nullable: true type: string status: description: >- Processing status of the audience (e.g. READY, PROCESSING, TOO_SMALL) example: READY type: string enum: - PROCESSING - ERROR - READY - TOO_SMALL type: description: Whether this audience is targeted or suppressed (excluded) example: TARGET type: string enum: - TARGET - SUPPRESS enabledAt: description: When the audience was enabled for this campaign (ISO 8601) example: '2025-03-01T12: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))$ required: - audienceId - name - status - type - enabledAt additionalProperties: false creativeFormats: description: >- Canonical creative format coverage for this campaign — URL-free format kinds required by selected products, covered by uploaded creatives, and still missing. Surface `missing` to prompt the user to upload the remaining creatives. type: object properties: required: type: array items: type: object properties: format_kind: type: string required: - format_kind additionalProperties: false covered: type: array items: type: object properties: format_kind: type: string required: - format_kind additionalProperties: false missing: type: array items: type: object properties: format_kind: type: string required: - format_kind additionalProperties: false required: - required - covered - missing additionalProperties: false propertyLists: description: >- Include/exclude property lists actually applied to this campaign via its media-buy packages. Only present when `includePropertyLists=true` is passed. An empty `propertyLists` array is the authoritative answer that no lists are applied; do not infer presence from the campaign brief or constraints. type: object properties: propertyLists: type: array items: type: object properties: listId: type: string name: type: string purpose: type: string enum: - include - exclude propertyCount: type: integer minimum: 0 maximum: 9007199254740991 createdAt: type: string updatedAt: type: string viaMediaBuys: type: array items: type: object properties: mediaBuyId: type: string packageIds: type: array items: type: string required: - mediaBuyId - packageIds additionalProperties: false required: - listId - name - purpose - propertyCount - createdAt - updatedAt - viaMediaBuys additionalProperties: false summary: type: object properties: totalLists: type: integer minimum: 0 maximum: 9007199254740991 includeCount: type: integer minimum: 0 maximum: 9007199254740991 excludeCount: type: integer minimum: 0 maximum: 9007199254740991 required: - totalLists - includeCount - excludeCount additionalProperties: false required: - propertyLists - summary additionalProperties: false mediaBuys: description: >- Media buys associated with this campaign. Present after execution; contains the product allocations, packages, and delivery data for each sales agent. type: array items: type: object properties: mediaBuyId: description: Unique identifier for the media buy type: string name: description: Media buy name type: string status: description: >- Current media buy status (e.g. DRAFT, ACTIVE, PAUSED, COMPLETED) type: string revision: description: >- Last authoritative provider revision observed for this media buy. type: integer minimum: 0 maximum: 9007199254740991 validActions: description: >- Provider-reported AdCP actions that are currently valid for this media buy. type: array items: type: string pendingAt: description: >- Which layer the media buy is parked at; only present while status is PENDING_APPROVAL. 'storefront' = waiting for the storefront operator's manual approval, 'salesagent' = the inventory source is still processing the buy, 'unknown' = the pending layer is indeterminate. type: string enum: - storefront - salesagent - unknown pendingReason: description: >- Why the buy is not delivering yet, rolled up to the most-blocking wait across its legs. An annotation derived from persisted forwarding state — never a status. Absent when the buy is delivering, terminal, or not storefront-routed. allOf: - $ref: '#/components/schemas/MediaBuyPendingReason' pendingSince: description: >- When the current wait began (ISO 8601). Present when pendingReason is set and the start of the wait is known. 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))$ errorCode: description: >- Buyer-safe structured error code when forwarding failed or the buy was rejected. Internal platform codes are mapped to this set and never emitted raw. allOf: - $ref: '#/components/schemas/BuyerMediaBuyErrorCode' errorOwner: description: >- Which party owns fixing the error. Present whenever errorCode is present. allOf: - $ref: '#/components/schemas/MediaBuyErrorOwner' sourceMessage: description: >- The source's rejection or moderation message, when one was provided — whitespace-collapsed, truncated, and known upstream identifiers removed. type: string forwardedAt: description: >- When the buy was forwarded to its inventory source(s) (ISO 8601). Absent when it has not been forwarded. 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))$ buyerReference: description: >- Support reference for this buy (`sf::`). Quote it with the request timestamp when contacting the seller or Scope3 support. example: sf:42:sf_mb_1783031864469_8pbc8mmr type: string startTime: description: >- When this media buy starts. Either "asap" (start immediately on activation) or an ISO 8601 date-time. Falls within the parent campaign's flightDates. example: '2025-04-14T00:00:00Z' type: string endTime: description: >- When this media buy ends, as an ISO 8601 date-time. Falls within the parent campaign's flightDates. example: '2025-04-30T23:59:59Z' type: string budget_denomination: description: >- Denomination marker: every budget on this media buy is GROSS (fee-inclusive) in the buyer currency. Present only for buys with locked fee terms (it travels with budget_breakdown); absent for legacy buys created before fee terms were locked, whose budgets pass through as stored. type: string enum: - gross budget_breakdown: description: >- Read-only gross/media/fee split of the buy's total budget at the fee terms locked when the media buy was created. Omitted for legacy buys created before fee terms were locked. Buyer surfaces only. type: object properties: media_budget: description: >- Media portion of the gross budget (gross minus the buyer fee) at the fee terms locked when the media buy was created, in major units. type: number fee_amount: description: >- Buyer fee carved from the gross budget at the locked fee rate, in major units. type: number fee_rate_percent: description: >- The Scope3 fee as a percentage of the media budget (fee ÷ media × 100). For example, a 5% fee on media produces a value of 5 here regardless of how the fee was stored internally. type: number effective_gross_cpm: description: >- Gross budget ÷ impression goal × 1000 — the CPM that makes "budget ÷ CPM = impressions" hold for the gross numbers the buyer operates on. Null when the buy has no positive impression goal. nullable: true type: number required: - media_budget - fee_amount - fee_rate_percent - effective_gross_cpm additionalProperties: false products: description: Products configured for this media buy type: array items: type: object properties: productId: description: Product identifier type: string productName: description: >- Human-readable product name. May be absent for products whose `products` cache row has not yet been populated. type: string publisherName: description: >- Publisher name for this product. May be absent for products whose `products` cache row has not yet been populated. type: string salesAgentName: description: Name of the sales agent for this product type: string budget: description: Budget allocated to this product type: number budgetCurrency: description: Currency for the budget type: string formatOptions: description: >- Publisher-declared format requirements for this product. Each entry has a stable format_option_id selector when supplied by the seller, a format_kind (e.g. "video_vast", "video_hosted", "image", "html5"), and a params object. For video products, check entries with format_kind "video_vast" or "video_hosted" for params.duration_ms_exact (required duration in ms), params.width and params.height (required pixel dimensions). type: array items: type: object properties: format_kind: type: string enum: - image - html5 - display_tag - image_carousel - video_hosted - video_vast - audio_hosted - audio_daast - sponsored_placement - native_in_feed - responsive_creative - agent_placement - custom params: type: object properties: width: type: integer maximum: 9007199254740991 minimum: 1 height: type: integer maximum: 9007199254740991 minimum: 1 sizes: minItems: 1 type: array items: type: object properties: width: type: integer maximum: 9007199254740991 minimum: 1 height: type: integer maximum: 9007199254740991 minimum: 1 required: - width - height additionalProperties: false min_width: type: integer maximum: 9007199254740991 minimum: 1 max_width: type: integer maximum: 9007199254740991 minimum: 1 min_height: type: integer maximum: 9007199254740991 minimum: 1 max_height: type: integer maximum: 9007199254740991 minimum: 1 duration_ms_exact: type: integer maximum: 9007199254740991 minimum: 1 duration_ms_range: type: array items: nullable: true type: number additionalProperties: {} format_option_id: type: string minLength: 1 required: - format_kind - params additionalProperties: false required: - productId additionalProperties: false pacingPeriods: description: >- Per-media-buy pacing schedule. When set, this buy is shaped by its own schedule rather than the campaign-level pacingPeriods. Each period includes a resolved budget; in weight mode, weights are preserved alongside the resolved budget. allOf: - $ref: '#/components/schemas/PacingPeriodsOutput' packages: description: Packages created after media buy execution type: array items: type: object properties: packageId: description: Package identifier type: string status: description: Package status (active, paused) type: string budget: description: Package budget amount type: number budgetCurrency: description: Budget currency code (e.g. USD) type: string pacing: description: Pacing strategy (even, asap, front_loaded) type: string bidPrice: description: Bid price for this package type: number startTime: description: >- Flight start date/time for this package (ISO 8601), if set. type: string endTime: description: >- Flight end date/time for this package (ISO 8601), if set. type: string targetingOverlay: allOf: - $ref: '#/components/schemas/CampaignPackageTargetingOverlay' providerTargeting: allOf: - $ref: '#/components/schemas/ProviderTargetingReadback' providerPlacementControls: type: object properties: placement_soft_opt_out: type: object properties: {} additionalProperties: false required: - placement_soft_opt_out additionalProperties: false requestedTargeting: description: >- Canonical targeting requested when Scope3 created this adapter package. allOf: - $ref: '#/components/schemas/ProviderTargetingReadback' targetingMatchesRequest: description: >- Whether the current provider-normalized targeting still equals the canonical request. type: boolean geoRegionMappings: description: ISO subdivision to provider-region identity evidence. type: array items: type: object properties: iso_code: type: string provider_key: type: string required: - iso_code - provider_key additionalProperties: false productIds: description: Product IDs in this package type: array items: type: string delivery: description: Delivery metrics for this package type: object properties: impressions: description: Delivered impressions type: number spend: description: >- Delivered spend in the buyer's GROSS (fee-inclusive) denomination, grossed up at the buy's pinned pricing terms. Net-as-reported for legacy buys with no pinned terms. type: number clicks: description: Click count nullable: true type: number required: - impressions - spend - clicks additionalProperties: false creatives: description: Creatives assigned to this package type: array items: type: object properties: creativeId: description: Creative manifest ID type: string name: description: Creative display name type: string formatId: description: Format ID for this creative type: object properties: id: description: Format identifier (e.g. display_300x250) type: string agent_url: description: ADCP agent URL this format belongs to type: string required: - id - agent_url additionalProperties: {} status: description: Creative status type: string sourceSyncStatus: description: >- Per-source creative sync verdicts. Empty array when the creative has not yet been synced to any source. type: array items: type: object properties: agentId: description: >- Legacy internal ADCP agent database ID, preserved for compatibility type: string sourceId: description: >- Public ADCP agent or inventory source ID captured for this creative sync route. A legacy-agent value is the protocol-level agent ID, never the numeric database ID; null means retained history predates a captured public source identity nullable: true type: string approvalStatus: description: >- Approval status returned by the source for this creative nullable: true type: string rejectionReason: description: >- Rejection reason returned by the source, if any nullable: true type: string required: - agentId - sourceId - approvalStatus - rejectionReason additionalProperties: false storefrontReviewStatus: description: >- Storefront operator review status for this creative. Null when the storefront uses automatic approval or the creative has not been submitted for review. nullable: true allOf: - $ref: '#/components/schemas/CreativeReviewStatus' required: - creativeId - name - formatId - status - sourceSyncStatus - storefrontReviewStatus additionalProperties: false required: - packageId - status - productIds additionalProperties: false optimizationGoals: description: >- Optimization goals applied to every package at execution time. Each goal is either `{ kind: "event", event_sources: [{ event_source_id, event_type }], target? }` or `{ kind: "metric", metric, target? }`. Event target kinds: `cost_per` (CPA), `per_ad_spend` (ROAS), `maximize_value`. Metric target kinds: `cost_per`, `threshold_rate`. type: array items: anyOf: - type: object properties: kind: type: string enum: - metric metric: anyOf: - type: string enum: - clicks - type: string enum: - views - type: string enum: - completed_views - type: string enum: - viewed_seconds - type: string enum: - attention_seconds - type: string enum: - attention_score - type: string enum: - engagements - type: string enum: - follows - type: string enum: - saves - type: string enum: - profile_visits - type: string enum: - reach reach_unit: anyOf: - type: string enum: - individuals - type: string enum: - households - type: string enum: - devices - type: string enum: - accounts - type: string enum: - cookies - type: string enum: - custom target_frequency: type: object properties: min: type: number minimum: 1 max: type: number minimum: 1 window: type: object properties: interval: type: number minimum: 1 unit: anyOf: - type: string enum: - seconds - type: string enum: - minutes - type: string enum: - hours - type: string enum: - days - type: string enum: - campaign required: - interval - unit additionalProperties: {} required: - window additionalProperties: {} view_duration_seconds: type: number target: anyOf: - type: object properties: kind: type: string enum: - cost_per value: type: number required: - kind - value additionalProperties: {} - type: object properties: kind: type: string enum: - threshold_rate value: type: number required: - kind - value additionalProperties: {} priority: type: number minimum: 1 required: - kind - metric additionalProperties: {} - type: object properties: kind: type: string enum: - event event_sources: type: array items: type: object properties: event_source_id: type: string minLength: 1 event_type: anyOf: - type: string enum: - page_view - type: string enum: - view_content - type: string enum: - select_content - type: string enum: - select_item - type: string enum: - search - type: string enum: - share - type: string enum: - add_to_cart - type: string enum: - remove_from_cart - type: string enum: - viewed_cart - type: string enum: - add_to_wishlist - type: string enum: - initiate_checkout - type: string enum: - add_payment_info - type: string enum: - purchase - type: string enum: - refund - type: string enum: - lead - type: string enum: - qualify_lead - type: string enum: - close_convert_lead - type: string enum: - disqualify_lead - type: string enum: - complete_registration - type: string enum: - subscribe - type: string enum: - follow - type: string enum: - content_view - type: string enum: - watch_milestone - type: string enum: - start_trial - type: string enum: - app_install - type: string enum: - app_launch - type: string enum: - contact - type: string enum: - schedule - type: string enum: - donate - type: string enum: - submit_application - type: string enum: - custom custom_event_name: type: string value_field: type: string value_factor: type: number required: - event_source_id - event_type additionalProperties: {} target: anyOf: - type: object properties: kind: type: string enum: - cost_per value: type: number required: - kind - value additionalProperties: {} - type: object properties: kind: type: string enum: - per_ad_spend value: type: number required: - kind - value additionalProperties: {} - type: object properties: kind: type: string enum: - maximize_value required: - kind additionalProperties: {} attribution_window: type: object properties: post_click: type: object properties: interval: type: number minimum: 1 unit: anyOf: - type: string enum: - seconds - type: string enum: - minutes - type: string enum: - hours - type: string enum: - days - type: string enum: - campaign required: - interval - unit additionalProperties: {} post_view: type: object properties: interval: type: number minimum: 1 unit: anyOf: - type: string enum: - seconds - type: string enum: - minutes - type: string enum: - hours - type: string enum: - days - type: string enum: - campaign required: - interval - unit additionalProperties: {} model: anyOf: - type: string enum: - last_touch - type: string enum: - first_touch - type: string enum: - linear - type: string enum: - time_decay - type: string enum: - data_driven additionalProperties: {} priority: type: number minimum: 1 required: - kind - event_sources additionalProperties: {} - type: object properties: kind: type: string enum: - vendor_metric vendor: type: object properties: domain: type: string pattern: >- ^[a-z0-9]([a-z0-9-]*[a-z0-9])?(\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)*$ brand_id: type: string industries: type: array items: type: string data_subject_contestation: type: object properties: url: type: string pattern: ^https:\/\/ email: type: string format: email pattern: >- ^(?!\.)(?!.*\.\.)([A-Za-z0-9_'+\-\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$ languages: type: array items: type: string additionalProperties: {} brand_kit_override: type: object properties: logo: type: object properties: asset_type: type: string enum: - image url: type: string width: type: number minimum: 1 height: type: number minimum: 1 format: type: string alt_text: type: string provenance: type: object properties: digital_source_type: anyOf: - type: string enum: - digital_capture - type: string enum: - digital_creation - type: string enum: - trained_algorithmic_media - type: string enum: - composite_with_trained_algorithmic_media - type: string enum: - algorithmic_media - type: string enum: - composite_capture - type: string enum: - composite_synthetic - type: string enum: - human_edits - type: string enum: - data_driven_media ai_tool: type: object properties: name: type: string version: type: string provider: type: string required: - name additionalProperties: {} human_oversight: anyOf: - type: string enum: - none - type: string enum: - prompt_only - type: string enum: - selected - type: string enum: - edited - type: string enum: - directed declared_by: type: object properties: agent_url: type: string role: anyOf: - type: string enum: - creator - type: string enum: - advertiser - type: string enum: - agency - type: string enum: - platform - type: string enum: - tool required: - role additionalProperties: {} declared_at: 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))$ created_time: 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))$ c2pa: type: object properties: manifest_url: type: string required: - manifest_url additionalProperties: {} embedded_provenance: type: array items: type: object properties: method: anyOf: - type: string enum: - manifest_wrapper - type: string enum: - provenance_markers standard: type: string provider: type: string verify_agent: type: object properties: agent_url: type: string pattern: ^https:\/\/ feature_id: type: string required: - agent_url additionalProperties: {} embedded_at: 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: - method - provider additionalProperties: {} watermarks: type: array items: type: object properties: media_type: anyOf: - type: string enum: - audio - type: string enum: - image - type: string enum: - video - type: string enum: - text provider: type: string verify_agent: type: object properties: agent_url: type: string pattern: ^https:\/\/ feature_id: type: string required: - agent_url additionalProperties: {} c2pa_action: anyOf: - type: string enum: - c2pa.watermarked.bound - type: string enum: - c2pa.watermarked.unbound embedded_at: 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: - media_type - provider additionalProperties: {} disclosure: type: object properties: required: type: boolean jurisdictions: type: array items: type: object properties: country: type: string region: type: string regulation: type: string label_text: type: string render_guidance: type: object properties: persistence: anyOf: - type: string enum: - continuous - type: string enum: - initial - type: string enum: - flexible min_duration_ms: type: number minimum: 1 positions: type: array items: anyOf: - type: string enum: - prominent - type: string enum: - footer - type: string enum: - audio - type: string enum: - subtitle - type: string enum: - overlay - type: string enum: - end_card - type: string enum: - pre_roll - type: string enum: - companion ext: type: object properties: {} additionalProperties: {} additionalProperties: {} required: - country - regulation additionalProperties: {} required: - required additionalProperties: {} verification: type: array items: type: object properties: verified_by: type: string verified_time: 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))$ result: anyOf: - type: string enum: - authentic - type: string enum: - ai_generated - type: string enum: - ai_modified - type: string enum: - inconclusive confidence: type: number minimum: 0 maximum: 1 details_url: type: string required: - verified_by - result additionalProperties: {} ext: type: object properties: {} additionalProperties: {} additionalProperties: {} required: - asset_type - url - width - height additionalProperties: {} colors: type: object properties: primary: type: string pattern: ^#[0-9a-fA-F]{6}$ secondary: type: string pattern: ^#[0-9a-fA-F]{6}$ accent: type: string pattern: ^#[0-9a-fA-F]{6}$ additionalProperties: {} voice: type: string tagline: type: string additionalProperties: {} required: - domain additionalProperties: {} metric_id: type: string target: anyOf: - type: object properties: kind: type: string enum: - cost_per value: type: number required: - kind - value additionalProperties: {} - type: object properties: kind: type: string enum: - threshold_rate value: type: number required: - kind - value additionalProperties: {} priority: type: number minimum: 1 required: - kind - vendor - metric_id additionalProperties: {} performance: description: >- Latest aggregate delivery snapshot for this media buy. windowStart/windowEnd identify the exact inclusive reporting period represented by the totals. type: object properties: impressions: description: Total impressions delivered type: number spend: description: >- Total delivered spend in the buyer's GROSS (fee-inclusive) denomination, grossed up at the buy's pinned pricing terms. Net-as-reported for legacy buys with no pinned terms. type: number clicks: description: Total clicks type: number views: description: Total views (engagement-qualified) type: number completedViews: description: Total completed views (video / audio completions) type: number conversions: description: Total attributed conversions type: number leads: description: Total leads type: number lastUpdated: description: When this snapshot was last refreshed (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))$ windowStart: description: >- Inclusive start date represented by this aggregate snapshot. type: string format: date 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])))$ windowEnd: description: Inclusive end date represented by this aggregate snapshot. type: string format: date 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])))$ required: - impressions - spend - clicks - views - completedViews - conversions - leads additionalProperties: false creatives: description: >- Creatives assigned to this media buy. Each entry includes source sync status across all sales agents. type: array items: type: object properties: creativeId: description: Creative manifest ID type: string name: description: Creative display name type: string formatId: description: Format ID for this creative type: object properties: id: description: Format identifier (e.g. display_300x250) type: string agent_url: description: ADCP agent URL this format belongs to type: string required: - id - agent_url additionalProperties: {} status: description: Creative status type: string sourceSyncStatus: description: >- Per-source creative sync verdicts. Empty array when the creative has not yet been synced to any source. type: array items: type: object properties: agentId: description: >- Legacy internal ADCP agent database ID, preserved for compatibility type: string sourceId: description: >- Public ADCP agent or inventory source ID captured for this creative sync route. A legacy-agent value is the protocol-level agent ID, never the numeric database ID; null means retained history predates a captured public source identity nullable: true type: string approvalStatus: description: >- Approval status returned by the source for this creative nullable: true type: string rejectionReason: description: Rejection reason returned by the source, if any nullable: true type: string required: - agentId - sourceId - approvalStatus - rejectionReason additionalProperties: false storefrontReviewStatus: description: >- Storefront operator review status for this creative. Null when the storefront uses automatic approval or the creative has not been submitted for review. nullable: true allOf: - $ref: '#/components/schemas/CreativeReviewStatus' required: - creativeId - name - formatId - status - sourceSyncStatus - storefrontReviewStatus additionalProperties: false createdAt: description: When the media buy was created (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))$ updatedAt: description: When the media buy was last updated (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: - mediaBuyId - name - status - createdAt - updatedAt additionalProperties: false 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))$ revision: description: >- Monotonically increasing revision counter. Incremented on every mutation. Pass as expectedRevision in save_campaign to enable optimistic concurrency. example: 1 default: 1 type: integer minimum: 1 maximum: 9007199254740991 dataDelivery: $ref: '#/components/schemas/CampaignDataDelivery' frequencyCaps: description: >- Buyer-side frequency cap configs for this campaign. Returned by `get_campaign`; not present on `list_campaigns` summary. type: array items: $ref: '#/components/schemas/FrequencyCapConfig' required: - campaignId - advertiserId - name - status - mode - management - optimizationApplyMode - createdAt - updatedAt - revision 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 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 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' MediaBuyRef: description: >- Lightweight media buy reference (id + live status). Used in Campaign.mediaBuyRefs so callers can enumerate media buys without loading the full nested tree. type: object properties: mediaBuyId: description: Unique identifier for the media buy example: mb_ETBn4gJ9Wu type: string status: description: >- Status of the LIVE media buy: what is delivering now (DRAFT, PENDING_APPROVAL, ACTIVE, PAUSED, COMPLETED, CANCELED). A buy that is ACTIVE with a change awaiting approval reports ACTIVE here and carries `pendingChange`; a queued change never replaces this value. example: ACTIVE type: string pendingAt: description: >- Which layer the media buy itself is parked at; only present while its own status is PENDING_APPROVAL (a buy awaiting its first approval). For a change queued behind an already-live buy, read `pendingChange.pendingAt`. 'storefront' = waiting for the storefront operator's manual approval, 'salesagent' = the inventory source is still processing the buy, 'unknown' = indeterminate. type: string enum: - storefront - salesagent - unknown pendingChange: $ref: '#/components/schemas/MediaBuyRefPendingChange' required: - mediaBuyId - status additionalProperties: false PacingPeriodsOutput: description: >- Defines a pacing schedule for a campaign. Periods represent time windows with varying spend intensity. Gaps between periods are treated as pauses (no spend). Use weight mode for relative intensity (e.g., 2x during holidays) or budget mode for explicit dollar amounts per period. type: object properties: mode: description: >- How period budgets are determined. "weight" uses relative weights to distribute the campaign budget proportionally. "budget" uses explicit dollar amounts per period. type: string enum: - weight - budget periods: description: Ordered list of pacing periods with date ranges and spend intensity minItems: 1 maxItems: 52 type: array items: type: object properties: label: description: >- Human-readable label for this period (e.g. "Memorial Day Heavy-Up") type: string minLength: 1 maxLength: 100 start: description: Period start date (YYYY-MM-DD, inclusive) type: string pattern: ^\d{4}-\d{2}-\d{2}$ end: description: Period end date (YYYY-MM-DD, inclusive) type: string pattern: ^\d{4}-\d{2}-\d{2}$ weight: description: >- Relative spend weight (1.0 = normal, 2.5 = 150% more, 0 = skip this period). Required when mode is "weight". type: number minimum: 0 maximum: 10 budget: description: >- Absolute budget for this period (0 = skip this period). Required when mode is "budget". type: number minimum: 0 required: - label - start - end additionalProperties: false required: - mode - periods additionalProperties: false 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 CampaignStorefrontRef: description: >- A storefront the campaign is pinned to, hydrated from the storefront IDs the buyer set on create/update. type: object properties: id: description: Storefront DB ID example: 42 type: integer maximum: 9007199254740991 minimum: 1 platformId: description: >- Public-facing storefront slug (the platform identifier returned by `list_storefronts`) example: acme-media type: string name: description: Storefront display name example: Acme Media type: string required: - id - platformId - name additionalProperties: false PerformanceConfigOutput: description: Configuration for performance campaign optimization type: object properties: optimizationGoals: description: >- Optimization goals for the campaign. Each goal targets either conversion events or seller-native metrics. minItems: 1 type: array items: $ref: '#/components/schemas/OptimizationGoalOutput' required: - optimizationGoals additionalProperties: false OptimizationApplyMode: description: >- Whether optimization suggestions are automatically applied or require human approval. type: string enum: - AUTO - MANUAL MediaBuyPendingReason: description: >- Why a not-yet-delivering media buy is waiting, and implicitly whose side owns the wait. A platform-derived annotation — never a status value. awaiting_storefront_approval / awaiting_source_moderation / creative_processing_at_source / awaiting_creative_approval = the seller side owns the wait; no_creatives_attached / source_rejected_creatives = the buyer owns it (attach or fix creatives); forward_failed_retrying / forward_failed_needs_correction = the platform owns it; accepted_awaiting_trafficking / scheduled_not_started = nothing is wrong, the buy is queued or scheduled. type: string enum: - forward_failed_needs_correction - forward_failed_retrying - awaiting_storefront_approval - awaiting_source_moderation - no_creatives_attached - source_rejected_creatives - creative_processing_at_source - awaiting_creative_approval - accepted_awaiting_trafficking - scheduled_not_started BuyerMediaBuyErrorCode: description: >- Buyer-safe structured error code for a media buy that failed to forward or was rejected. Paired with errorOwner (who owns the fix) and, when the source provided one, a sanitized human-readable message. type: string enum: - product_no_longer_available - source_rejected - storefront_rejected - source_unavailable - invalid_request - quote_expired - platform_error MediaBuyErrorOwner: description: >- Which party owns fixing the error: buyer_input (the request needs a correction from the buyer), platform (Scope3 owns the fault), seller (the storefront or its source made the decision or is unavailable). type: string enum: - buyer_input - platform - seller CampaignPackageTargetingOverlay: description: >- Targeting carried on a campaign package; directed adapters populate provider-normalized readback when supported. 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: {} daypart_targets: type: array items: type: object properties: days: type: array items: anyOf: - type: string enum: - monday - type: string enum: - tuesday - type: string enum: - wednesday - type: string enum: - thursday - type: string enum: - friday - type: string enum: - saturday - type: string enum: - sunday start_hour: type: number minimum: 0 maximum: 23 end_hour: type: number minimum: 1 maximum: 24 label: type: string required: - days - start_hour - end_hour additionalProperties: {} axe_include_segment: type: string axe_exclude_segment: type: string audience_include: type: array items: type: string audience_exclude: type: array items: type: string signal_targeting_groups: type: object properties: operator: type: string enum: - all groups: type: array items: type: object properties: operator: anyOf: - type: string enum: - any - type: string enum: - none signals: type: array items: type: object properties: pricing_option_id: type: string signal_agent_segment_id: type: string activation_key: anyOf: - type: object properties: type: type: string enum: - segment_id segment_id: type: string required: - type - segment_id additionalProperties: {} - type: object properties: type: type: string enum: - key_value key: type: string value: type: string required: - type - key - value additionalProperties: {} additionalProperties: {} required: - operator - signals additionalProperties: {} required: - operator - groups additionalProperties: {} signal_targeting: type: array items: anyOf: - type: object properties: signal_ref: anyOf: - type: object properties: scope: type: string enum: - product signal_id: type: string pattern: ^[a-zA-Z0-9_-]+$ required: - scope - signal_id additionalProperties: {} - type: object properties: scope: type: string enum: - data_provider data_provider_domain: type: string pattern: >- ^[a-z0-9]([a-z0-9-]*[a-z0-9])?(\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)*$ signal_id: type: string pattern: ^[a-zA-Z0-9_-]+$ required: - scope - data_provider_domain - signal_id additionalProperties: {} - type: object properties: scope: type: string enum: - signal_source signal_source_url: type: string signal_id: type: string pattern: ^[a-zA-Z0-9_-]+$ required: - scope - signal_source_url - signal_id additionalProperties: {} signal_id: anyOf: - type: object properties: source: type: string enum: - catalog data_provider_domain: type: string pattern: >- ^[a-z0-9]([a-z0-9-]*[a-z0-9])?(\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)*$ id: type: string pattern: ^[a-zA-Z0-9_-]+$ required: - source - data_provider_domain - id additionalProperties: {} - type: object properties: source: type: string enum: - agent agent_url: type: string id: type: string pattern: ^[a-zA-Z0-9_-]+$ required: - source - agent_url - id additionalProperties: {} value_type: type: string enum: - binary value: type: boolean required: - value_type - value additionalProperties: {} - type: object properties: signal_ref: anyOf: - type: object properties: scope: type: string enum: - product signal_id: type: string pattern: ^[a-zA-Z0-9_-]+$ required: - scope - signal_id additionalProperties: {} - type: object properties: scope: type: string enum: - data_provider data_provider_domain: type: string pattern: >- ^[a-z0-9]([a-z0-9-]*[a-z0-9])?(\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)*$ signal_id: type: string pattern: ^[a-zA-Z0-9_-]+$ required: - scope - data_provider_domain - signal_id additionalProperties: {} - type: object properties: scope: type: string enum: - signal_source signal_source_url: type: string signal_id: type: string pattern: ^[a-zA-Z0-9_-]+$ required: - scope - signal_source_url - signal_id additionalProperties: {} signal_id: anyOf: - type: object properties: source: type: string enum: - catalog data_provider_domain: type: string pattern: >- ^[a-z0-9]([a-z0-9-]*[a-z0-9])?(\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)*$ id: type: string pattern: ^[a-zA-Z0-9_-]+$ required: - source - data_provider_domain - id additionalProperties: {} - type: object properties: source: type: string enum: - agent agent_url: type: string id: type: string pattern: ^[a-zA-Z0-9_-]+$ required: - source - agent_url - id additionalProperties: {} value_type: type: string enum: - categorical values: type: array items: type: string required: - value_type - values additionalProperties: {} - type: object properties: signal_ref: anyOf: - type: object properties: scope: type: string enum: - product signal_id: type: string pattern: ^[a-zA-Z0-9_-]+$ required: - scope - signal_id additionalProperties: {} - type: object properties: scope: type: string enum: - data_provider data_provider_domain: type: string pattern: >- ^[a-z0-9]([a-z0-9-]*[a-z0-9])?(\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)*$ signal_id: type: string pattern: ^[a-zA-Z0-9_-]+$ required: - scope - data_provider_domain - signal_id additionalProperties: {} - type: object properties: scope: type: string enum: - signal_source signal_source_url: type: string signal_id: type: string pattern: ^[a-zA-Z0-9_-]+$ required: - scope - signal_source_url - signal_id additionalProperties: {} signal_id: anyOf: - type: object properties: source: type: string enum: - catalog data_provider_domain: type: string pattern: >- ^[a-z0-9]([a-z0-9-]*[a-z0-9])?(\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)*$ id: type: string pattern: ^[a-zA-Z0-9_-]+$ required: - source - data_provider_domain - id additionalProperties: {} - type: object properties: source: type: string enum: - agent agent_url: type: string id: type: string pattern: ^[a-zA-Z0-9_-]+$ required: - source - agent_url - id additionalProperties: {} value_type: type: string enum: - numeric min_value: type: number max_value: type: number required: - value_type additionalProperties: {} frequency_cap: type: object properties: suppress: type: object properties: interval: type: number minimum: 1 unit: anyOf: - type: string enum: - seconds - type: string enum: - minutes - type: string enum: - hours - type: string enum: - days - type: string enum: - campaign required: - interval - unit additionalProperties: {} suppress_minutes: type: number minimum: 0 max_impressions: type: number minimum: 1 per: anyOf: - type: string enum: - individuals - type: string enum: - households - type: string enum: - devices - type: string enum: - accounts - type: string enum: - cookies - type: string enum: - custom window: type: object properties: interval: type: number minimum: 1 unit: anyOf: - type: string enum: - seconds - type: string enum: - minutes - type: string enum: - hours - type: string enum: - days - type: string enum: - campaign required: - interval - unit additionalProperties: {} additionalProperties: {} property_list: type: object properties: agent_url: type: string list_id: type: string minLength: 1 auth_token: type: string required: - agent_url - list_id additionalProperties: {} collection_list: type: object properties: agent_url: type: string list_id: type: string minLength: 1 auth_token: type: string required: - agent_url - list_id additionalProperties: {} collection_list_exclude: type: object properties: agent_url: type: string list_id: type: string minLength: 1 auth_token: type: string required: - agent_url - list_id additionalProperties: {} age_restriction: type: object properties: min: type: number minimum: 13 maximum: 99 verification_required: type: boolean accepted_methods: type: array items: anyOf: - type: string enum: - facial_age_estimation - type: string enum: - id_document - type: string enum: - digital_id - type: string enum: - credit_card - type: string enum: - world_id required: - min additionalProperties: {} 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 store_catchments: type: array items: type: object properties: catalog_id: type: string store_ids: type: array items: type: string catchment_ids: type: array items: type: string required: - catalog_id additionalProperties: {} geo_proximity: type: array items: anyOf: - type: object properties: lat: type: number minimum: -90 maximum: 90 lng: type: number minimum: -180 maximum: 180 label: type: string travel_time: type: object properties: value: type: number minimum: 1 unit: anyOf: - type: string enum: - min - type: string enum: - hr required: - value - unit additionalProperties: {} transport_mode: anyOf: - type: string enum: - walking - type: string enum: - cycling - type: string enum: - driving - type: string enum: - public_transport ext: type: object properties: {} additionalProperties: {} required: - lat - lng - travel_time - transport_mode additionalProperties: {} - type: object properties: lat: type: number minimum: -90 maximum: 90 lng: type: number minimum: -180 maximum: 180 label: type: string transport_mode: anyOf: - type: string enum: - walking - type: string enum: - cycling - type: string enum: - driving - type: string enum: - public_transport radius: type: object properties: value: type: number unit: anyOf: - type: string enum: - km - type: string enum: - mi - type: string enum: - m required: - value - unit additionalProperties: {} ext: type: object properties: {} additionalProperties: {} required: - lat - lng - radius additionalProperties: {} - type: object properties: lat: type: number minimum: -90 maximum: 90 lng: type: number minimum: -180 maximum: 180 label: type: string transport_mode: anyOf: - type: string enum: - walking - type: string enum: - cycling - type: string enum: - driving - type: string enum: - public_transport geometry: type: object properties: type: anyOf: - type: string enum: - Polygon - type: string enum: - MultiPolygon coordinates: type: array items: {} required: - type - coordinates additionalProperties: {} ext: type: object properties: {} additionalProperties: {} required: - geometry additionalProperties: {} language: type: array items: type: string keyword_targets: type: array items: type: object properties: keyword: type: string minLength: 1 match_type: anyOf: - type: string enum: - broad - type: string enum: - phrase - type: string enum: - exact bid_price: type: number minimum: 0 required: - keyword - match_type additionalProperties: {} negative_keywords: type: array items: type: object properties: keyword: type: string minLength: 1 match_type: anyOf: - type: string enum: - broad - type: string enum: - phrase - type: string enum: - exact required: - keyword - match_type additionalProperties: {} additionalProperties: {} ProviderTargetingReadback: description: >- Provider-normalized geographic, demographic, and audience targeting readback. Audience fields contain canonical buyer IDs, never native provider IDs. Only canonical allowlisted fields are exposed; raw provider extensions are never returned. type: object properties: countries: type: array items: type: string regions: type: array items: type: string cities: type: array items: type: string zips: type: array items: type: string age_min: description: >- Provider-normalized minimum age. Readback can include provider-authored 13–17 targeting even though Scope3 controlled brief writes currently start at 18. type: integer minimum: 13 maximum: 65 age_max: description: >- Provider-normalized maximum age; 65 represents the provider 65+ upper bucket. type: integer minimum: 13 maximum: 65 genders: description: >- Provider-normalized gender restrictions. An empty array means unrestricted/all genders. type: array items: type: string enum: - FEMALE - MALE audience_include: description: >- Canonical buyer audience IDs confirmed as positively targeted. Native provider audience IDs are never exposed. type: array items: type: string minLength: 1 audience_exclude: description: >- Canonical buyer audience IDs confirmed as excluded. Native provider audience IDs are never exposed. type: array items: type: string minLength: 1 publisher_platforms: type: array items: type: string enum: - facebook - instagram facebook_positions: type: array items: type: string enum: - facebook_reels - feed - story instagram_positions: type: array items: type: string enum: - reels - story - stream threads_positions: type: array items: type: string enum: - threads_stream instream_video_skippable_excluded: type: boolean required: - countries - regions - cities - zips additionalProperties: false CreativeReviewStatus: description: >- Lifecycle state of a buyer-submitted creative awaiting storefront review. `pending` until an operator decides; `approved` or `rejected` after a decision; `revoked` if an operator pulls a previously-approved creative. type: string enum: - pending - approved - rejected - revoked CampaignDataDelivery: description: >- Resolved data-delivery configuration for this campaign. Groups standing Data Delivery Outputs (with advertiser/campaign-scoped overrides applied). Distinct from media-buy reporting fields elsewhere in the API. type: object properties: outputs: description: >- Resolved Data Delivery Outputs for this campaign. Campaign-scoped Outputs override advertiser-scoped Outputs by `dataDeliveryType`. Each entry is tagged with `source` ("advertiser" or "campaign"). type: array items: $ref: '#/components/schemas/DataDeliveryOutput' additionalProperties: false FrequencyCapConfig: description: Buyer-side frequency cap configuration type: object properties: max_impressions: description: Maximum number of impressions allowed within the window example: 3 type: integer maximum: 9007199254740991 minimum: 1 window: $ref: '#/components/schemas/FrequencyCapWindow' id: description: Unique identifier for the frequency cap config example: '12345' type: string targetLevel: description: Level of the entity the cap applies to allOf: - $ref: '#/components/schemas/FrequencyCapTargetLevel' targetId: description: >- Identifier of the entity at the chosen target level: advertiser_id when targetLevel is ADVERTISER, campaign_id when CAMPAIGN, creative_id when CREATIVE. example: camp_abc123 type: string createdAt: description: ISO 8601 creation timestamp type: string updatedAt: description: ISO 8601 last-updated timestamp type: string archivedAt: description: ISO 8601 archive timestamp; null for active configs nullable: true type: string required: - max_impressions - window - id - targetLevel - targetId - createdAt - updatedAt additionalProperties: {} 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 MediaBuyRefPendingChange: description: >- Present when this buy has a submitted change that has not yet reached the delivering buy. Call `get_media_buy` for the field-level differences; this reference stays lightweight by design. type: object properties: status: description: Lifecycle status of the queued change, typically PENDING_APPROVAL. example: PENDING_APPROVAL type: string pendingAt: description: Which layer the queued change is parked at. type: string enum: - storefront - salesagent - unknown required: - status additionalProperties: false OptimizationGoalOutput: description: >- A single optimization target. Either kind "event" (conversion events) or kind "metric" (seller-native delivery metric). oneOf: - $ref: '#/components/schemas/EventGoalOutput' - $ref: '#/components/schemas/MetricGoalOutput' type: object discriminator: propertyName: kind mapping: event: $ref: '#/components/schemas/EventGoalOutput' metric: $ref: '#/components/schemas/MetricGoalOutput' DataDeliveryOutput: description: Resolved Data Delivery Output as returned by the API. type: object properties: outputConfigId: description: Database identifier for the underlying output config row. type: string dataDeliveryType: type: string enum: - MB_DELIVERY - IMPRESSIONS - CLICKS - VAST_EVENTS - CAPI_ATTRIBUTION - MMP_POSTBACKS cadence: type: string enum: - HOURLY - DAILY - WEEKLY syncWeeklyDay: type: integer minimum: 0 maximum: 6 enabled: type: boolean credentialId: description: >- Database identifier of the Data Delivery Credential authenticating this Output. type: string credentialName: description: >- Name of the Data Delivery Credential authenticating this Output (advertiser-scoped, unique among live credentials). type: string deliveryConfig: $ref: '#/components/schemas/DeliveryConfigOutput' source: description: >- Where this Output was configured — "advertiser" for default, "campaign" for an override. type: string enum: - advertiser - campaign createdAt: type: string updatedAt: type: string required: - outputConfigId - dataDeliveryType - cadence - enabled - credentialId - credentialName - deliveryConfig - source - createdAt - updatedAt additionalProperties: false FrequencyCapWindow: description: >- Rolling time window over which max_impressions applies (AdCP Duration shape). type: object properties: interval: type: number minimum: 1 unit: anyOf: - type: string enum: - seconds - type: string enum: - minutes - type: string enum: - hours - type: string enum: - days - type: string enum: - campaign required: - interval - unit additionalProperties: {} FrequencyCapTargetLevel: description: Level of the entity the frequency cap applies to type: string enum: - ADVERTISER - CAMPAIGN - CREATIVE EventGoalOutput: description: Optimize for advertiser-tracked conversion events via event sources. type: object properties: kind: type: string enum: - event eventSources: description: >- Event source and type pairs feeding this goal. Seller deduplicates by event_id across entries. minItems: 1 type: array items: type: object properties: eventSourceId: description: >- Event source to include (must be configured via sync_event_sources) example: website_pixel type: string minLength: 1 eventType: description: IAB ECAPI event type to optimize for type: string enum: - page_view - view_content - select_content - select_item - search - share - add_to_cart - remove_from_cart - viewed_cart - add_to_wishlist - initiate_checkout - add_payment_info - purchase - refund - lead - qualify_lead - close_convert_lead - disqualify_lead - complete_registration - subscribe - follow - content_view - watch_milestone - start_trial - app_install - app_launch - contact - schedule - donate - submit_application - custom customEventName: description: >- Required when eventType is 'custom'. Platform-specific custom event name. type: string valueField: description: >- Field on custom_data carrying the monetary value. Required when target is 'per_ad_spend'. example: value type: string valueFactor: description: >- Multiplier for valueField (default 1). Use -1 for refunds, 0.01 for cents. example: 1 type: number required: - eventSourceId - eventType additionalProperties: false target: description: >- Target cost or return. When omitted, the seller maximizes conversions within budget. oneOf: - type: object properties: kind: type: string enum: - cost_per value: description: Target cost per unit in buy currency example: 25 type: number minimum: 0 exclusiveMinimum: true required: - kind - value additionalProperties: false - type: object properties: kind: type: string enum: - per_ad_spend value: description: Target return ratio (e.g. 4.0 = $4 of value per $1 spent) example: 4 type: number minimum: 0 exclusiveMinimum: true required: - kind - value additionalProperties: false - type: object properties: kind: type: string enum: - maximize_value required: - kind additionalProperties: false type: object attributionWindow: description: >- Attribution window for this goal. When omitted, the seller uses their default. allOf: - $ref: '#/components/schemas/OptimizationAttributionWindowOutput' priority: description: >- Priority among goals on this package. 1 = highest. When omitted, sellers use array position. example: 1 type: integer minimum: 1 maximum: 9007199254740991 required: - kind - eventSources additionalProperties: false MetricGoalOutput: description: Optimize for a seller-tracked delivery metric. No event source required. type: object properties: kind: type: string enum: - metric metric: description: >- Seller-native metric to optimize for. Delivery metrics: clicks, views (viewable impressions, per AdCP), completed_views (video/audio completions, qualified by viewDurationSeconds). Duration/score: viewed_seconds, attention_seconds, attention_score. Audience action: engagements, follows, saves, profile_visits. To target a viewability rate, use metric: 'views' with a threshold_rate target (proportion of impressions). type: string enum: - clicks - views - completed_views - viewed_seconds - attention_seconds - attention_score - engagements - follows - saves - profile_visits - reach viewDurationSeconds: description: >- Minimum video view duration in seconds for completed_view. Only applicable when metric is 'completed_views'. type: number minimum: 0 exclusiveMinimum: true target: description: >- Target for this metric. When omitted, the seller maximizes metric volume within budget. oneOf: - type: object properties: kind: type: string enum: - cost_per value: description: Target cost per unit in buy currency example: 25 type: number minimum: 0 exclusiveMinimum: true required: - kind - value additionalProperties: false - type: object properties: kind: type: string enum: - threshold_rate value: description: >- Minimum per-impression value. Units depend on metric: proportion (clicks, views), seconds (viewed_seconds, attention_seconds), or score (attention_score). example: 0.001 type: number minimum: 0 exclusiveMinimum: true required: - kind - value additionalProperties: false type: object priority: description: >- Priority among goals on this package. 1 = highest. When omitted, sellers use array position. example: 2 type: integer minimum: 1 maximum: 9007199254740991 required: - kind - metric additionalProperties: false DeliveryConfigOutput: description: >- Per-Output destination shape (non-secret). Additional destination types are added as new variants in this discriminated union. oneOf: - $ref: '#/components/schemas/GcsDeliveryConfigOutput' - $ref: '#/components/schemas/S3DeliveryConfigOutput' - $ref: '#/components/schemas/AzureBlobDeliveryConfigOutput' type: object discriminator: propertyName: type mapping: GCS: $ref: '#/components/schemas/GcsDeliveryConfigOutput' S3: $ref: '#/components/schemas/S3DeliveryConfigOutput' AZURE_BLOB: $ref: '#/components/schemas/AzureBlobDeliveryConfigOutput' OptimizationAttributionWindowOutput: description: Attribution window for conversion optimization type: object properties: postClick: description: Click-through attribution window example: interval: 7 unit: days allOf: - $ref: '#/components/schemas/DurationOutput' postView: description: View-through attribution window example: interval: 1 unit: days allOf: - $ref: '#/components/schemas/DurationOutput' required: - postClick additionalProperties: false GcsDeliveryConfigOutput: type: object properties: type: type: string enum: - GCS pathPrefix: description: >- Object key prefix within the credential's bucket. Leading slashes are not stripped. The tokens {YYYY}, {MM}, {DD}, {HH} (from the delivery period start, UTC) and {DATA_DELIVERY_TYPE} are substituted at delivery time — e.g. "lld/{YYYY}/{MM}/{DD}/{HH}/{DATA_DELIVERY_TYPE}/" → "lld/2026/06/03/14/IMPRESSIONS/". Any other text is used verbatim. default: '' type: string maxLength: 1024 format: default: JSONL type: string enum: - JSONL - PARQUET - CSV required: - type - pathPrefix - format additionalProperties: false S3DeliveryConfigOutput: type: object properties: type: type: string enum: - S3 pathPrefix: description: >- Object key prefix within the credential's S3 bucket. Leading slashes are not stripped. The tokens {YYYY}, {MM}, {DD}, {HH} (from the delivery period start, UTC) and {DATA_DELIVERY_TYPE} are substituted at delivery time — e.g. "lld/{YYYY}/{MM}/{DD}/{HH}/{DATA_DELIVERY_TYPE}/" → "lld/2026/06/03/14/IMPRESSIONS/". Any other text is used verbatim. default: '' type: string maxLength: 1024 format: default: JSONL type: string enum: - JSONL - PARQUET - CSV required: - type - pathPrefix - format additionalProperties: false AzureBlobDeliveryConfigOutput: type: object properties: type: type: string enum: - AZURE_BLOB pathPrefix: description: >- Blob name prefix within the credential's Azure container. Leading slashes are not stripped. The tokens {YYYY}, {MM}, {DD}, {HH} (from the delivery period start, UTC) and {DATA_DELIVERY_TYPE} are substituted at delivery time — e.g. "lld/{YYYY}/{MM}/{DD}/{HH}/{DATA_DELIVERY_TYPE}/" → "lld/2026/06/03/14/IMPRESSIONS/". Any other text is used verbatim. default: '' type: string maxLength: 1024 format: default: JSONL type: string enum: - JSONL - PARQUET - CSV required: - type - pathPrefix - format additionalProperties: false DurationOutput: description: A duration expressed as an interval and unit type: object properties: interval: type: integer maximum: 9007199254740991 minimum: 1 unit: type: string enum: - minutes - hours - days - campaign required: - interval - unit additionalProperties: false securitySchemes: bearerAuth: type: http scheme: bearer description: API key or access token ````