> ## Documentation Index > Fetch the complete documentation index at: https://docs.apostra.com/llms.txt > Use this file to discover all available pages before exploring further. # List every media buy on the storefront > The union of routed buys (approval queue + per-source forwarding routes) and ESA-managed buys, with status filters. Default sort is urgency: buys still waiting on someone whose flight starts within 48 hours come first. Each row carries the shared `pendingReason` vocabulary (the same enum buyers see), the latest structured error code, and the forward outcome. ## OpenAPI ````yaml /v2/storefront-api-v2.yaml get /media-buys openapi: 3.0.0 info: title: Scope3 Storefront API version: 2.0.0 description: >- REST API for partners to manage Seller Accounts, inventory sources, and billing. ## Authentication All endpoints require a Bearer token in the Authorization header: ``` Authorization: Bearer your-api-key ``` ## Base URL `https://api.apostra.com/api/v2/storefront` ## For AI Agents AI agents can use the MCP endpoint at `/mcp/v2/storefront` 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.apostra.com/api/v2/storefront description: Production server security: [] tags: - 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: Storefront description: Manage storefront and inventory sources - name: Storefront Agents description: List and manage registered sales, signals, and outcomes agents - name: Storefront Activity description: Audit log of configuration and inventory changes on the storefront - name: Storefront Billing description: Payout bank details and billing configuration for Seller Accounts - name: AI Usage description: Seller Account AI token usage visibility by model - name: MCP description: Model Context Protocol endpoints paths: /media-buys: get: tags: - Storefront summary: List every media buy on the storefront description: >- The union of routed buys (approval queue + per-source forwarding routes) and ESA-managed buys, with status filters. Default sort is urgency: buys still waiting on someone whose flight starts within 48 hours come first. Each row carries the shared `pendingReason` vocabulary (the same enum buyers see), the latest structured error code, and the forward outcome. operationId: listStorefrontMediaBuys parameters: - in: query name: status schema: description: Filter to one seller lifecycle state. allOf: - $ref: '#/components/schemas/SellerMediaBuyStatus' description: Filter to one seller lifecycle state. - in: query name: buyerCustomerId schema: description: Filter to one buyer (customer id). type: integer minimum: 0 exclusiveMinimum: true maximum: 9007199254740991 description: Filter to one buyer (customer id). - in: query name: accountRelationshipId schema: description: >- Filter to one seller-owned account relationship. This is the authoritative transaction boundary for an External advertiser, never a buyer-id heuristic. type: string pattern: ^[1-9][0-9]*$ description: >- Filter to one seller-owned account relationship. This is the authoritative transaction boundary for an External advertiser, never a buyer-id heuristic. - in: query name: sourceId schema: description: >- Filter to buys with a leg on this inventory source (routed buys) or managed by this ad server source. type: string minLength: 1 description: >- Filter to buys with a leg on this inventory source (routed buys) or managed by this ad server source. - in: query name: flightStartFrom schema: description: Only buys whose flight starts at/after this instant. 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))$ description: Only buys whose flight starts at/after this instant. - in: query name: flightStartTo schema: description: Only buys whose flight starts at/before this instant. 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))$ description: Only buys whose flight starts at/before this instant. - in: query name: activeOnly schema: description: >- Exclude buys that are finished and cannot need anyone: `completed`, `canceled` and `rejected`. The default list is the complete inventory, but a surface asking "what needs me now" wants only live work — and because the list is newest-first, a buy that settled yesterday otherwise outranks an older buy that is still running. default: false type: boolean description: >- Exclude buys that are finished and cannot need anyone: `completed`, `canceled` and `rejected`. The default list is the complete inventory, but a surface asking "what needs me now" wants only live work — and because the list is newest-first, a buy that settled yesterday otherwise outranks an older buy that is still running. - in: query name: sort schema: default: urgency description: >- `urgency` (default) is the stable list order: buys still waiting on someone whose flight starts within 48h first, then by flight start, then newest. `attention` re-orders THIS PAGE by what needs the seller — money the flight will not deliver, then work waiting on the seller, then a goal being missed. Because that ranking needs delivery and goal verdicts that exist only after the page is hydrated, it ranks a page and never the storefront, so it is REJECTED with `skip` above 0 rather than quietly served in urgency order. The response echoes `attentionRanked`. type: string enum: - urgency - attention description: >- `urgency` (default) is the stable list order: buys still waiting on someone whose flight starts within 48h first, then by flight start, then newest. `attention` re-orders THIS PAGE by what needs the seller — money the flight will not deliver, then work waiting on the seller, then a goal being missed. Because that ranking needs delivery and goal verdicts that exist only after the page is hydrated, it ranks a page and never the storefront, so it is REJECTED with `skip` above 0 rather than quietly served in urgency order. The response echoes `attentionRanked`. - in: query name: take schema: default: 50 description: Page size (max 200). type: integer minimum: 0 exclusiveMinimum: true maximum: 200 description: Page size (max 200). - in: query name: skip schema: default: 0 description: Rows to skip (offset pagination over the sorted list). type: integer minimum: 0 maximum: 9007199254740991 description: Rows to skip (offset pagination over the sorted list). responses: '200': description: List every media buy on the storefront content: application/json: schema: $ref: '#/components/schemas/StorefrontMediaBuyListResponse' '400': description: Bad request content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: No storefront exists for the calling operator. 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: SellerMediaBuyStatus: type: string enum: - pending_approval - forwarding - forward_failed - awaiting_source - rejected - canceled - booked - delivering - paused - completed description: >- Coarse seller-facing lifecycle of a buy on the storefront, derived from persisted approval + forwarding state. A platform list-view convenience — not an AdCP MediaBuyStatus. Use the per-buy timeline for the exact underlying states. StorefrontMediaBuyListResponse: type: object properties: items: type: array items: $ref: '#/components/schemas/StorefrontMediaBuySummary' total: type: integer minimum: 0 maximum: 9007199254740991 description: Total rows matching the filters (before pagination). warnings: type: array items: type: string description: >- Non-fatal data-source problems (e.g. an upstream source that could not be reached). Empty when every source answered. attentionRanked: type: boolean description: >- True when `items` was re-ordered by what needs the seller. The ranking covers THIS PAGE only — the tiers depend on delivery and goal verdicts that exist only after hydration — so a page is never evidence of the storefront's worst buys. False on the default urgency order, which is a stable server-side sort over the whole population. statusFreshness: nullable: true description: >- Non-null when this storefront routes buys through an ad-platform connection whose status sync has been failing long enough that displayed statuses may be out of date. Null when statuses are current (or the storefront has no such connection). type: object properties: lastConfirmedAt: nullable: true description: >- When statuses were last successfully confirmed with the ad platform. Null when no sync has ever succeeded. 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))$ hoursSinceConfirmed: nullable: true description: >- Whole hours since the last successful status sync. Null when no sync has ever succeeded. type: integer minimum: 0 maximum: 9007199254740991 message: type: string description: >- Seller-facing staleness note, e.g. "status last confirmed 5h ago — source unreachable". required: - lastConfirmedAt - hoursSinceConfirmed - message additionalProperties: false delivery: nullable: true description: >- Relationship delivery rollup. Null means none of the matching buys has a delivery record, never a zero-valued delivery total. type: object properties: impressions: type: number minimum: 0 spend: type: number minimum: 0 pacingAgainstBookedBudget: nullable: true type: number minimum: 0 lastDeliveryDate: type: string pattern: ^\d{4}-\d{2}-\d{2}$ required: - impressions - spend - pacingAgainstBookedBudget - lastDeliveryDate additionalProperties: false required: - items - total - warnings - attentionRanked - statusFreshness - delivery additionalProperties: false description: >- Every buy on the storefront — the union of routed and source-managed buys — urgency-sorted by default. ErrorResponse: type: object properties: data: type: string nullable: true enum: - null error: $ref: '#/components/schemas/ApiError' required: - data - error additionalProperties: false description: Standard error response StorefrontMediaBuySummary: type: object properties: mediaBuyId: type: string description: >- The media buy id at this storefront grain (`sf_mb_…` for routed buys; the upstream source id for source-managed buys). kind: type: string enum: - routed - esa description: >- Where this buy is managed: `routed` = forwarded through the storefront routing layer (approval queue + per-source routes); `esa` = managed by an ad server source upstream (`esa` is the stable wire value). buyer: type: object properties: customerId: nullable: true description: >- Buyer customer id (null for upstream source principals with no platform customer). type: integer minimum: -9007199254740991 maximum: 9007199254740991 name: nullable: true description: Buyer display name when known. type: string required: - customerId - name additionalProperties: false description: Who bought it. advertiser: type: object properties: name: nullable: true type: string required: - name additionalProperties: false description: >- The advertiser/brand named in the seller-visible transaction payload, when present. operator: type: object properties: name: nullable: true type: string required: - name additionalProperties: false description: >- The buying-operator domain recorded on the persisted transaction account reference. This is deliberately separate from the advertised brand and is null rather than substituted with a buyer-customer display name. commercial: type: object properties: budget: nullable: true type: number minimum: 0 currency: nullable: true type: string denomination: nullable: true description: >- `net_media` is the seller-authorized amount after buyer-side fees; `source_total` is an upstream source total whose gross/net denomination is not declared by that contract. type: string enum: - net_media - source_total cpm: nullable: true description: >- Seller-visible CPM when the transaction contract supplies enough information to derive it; null rather than guessed. type: number minimum: 0 required: - budget - currency - denomination - cpm additionalProperties: false description: >- Seller-authorized commercial context. Buyer-only gross budget and fee details are never exposed here. delivery: nullable: true description: >- Delivery the storefront reporting pipeline reported for this buy. Null means it has reported nothing; it is never a zero-valued report, and `reporting` says why. A buy an ad server manages is never reported here — read `adServerDelivery`. allOf: - $ref: '#/components/schemas/StorefrontMediaBuyDelivery' adServerDelivery: nullable: true description: >- The managing ad server's own running total for a source-managed buy, denominated in `commercial.currency`. Null for a routed buy, and null when the ad server has not answered. It names no reporting day: an ad server states a cumulative total without saying which day it runs through. allOf: - $ref: '#/components/schemas/StorefrontMediaBuyAdServerDelivery' attention: nullable: true description: >- What needs the seller on this buy, and how loudly. Null only on a read that did not hydrate delivery and the goal, which the list always does. allOf: - $ref: '#/components/schemas/StorefrontMediaBuyAttention' goal: nullable: true description: >- The buyer's goal for this buy and how delivery compares — the same verdict the buyer sees. Null when this seller holds no goal for the buy: no commitment of its own and no `optimization_goals` on the payload it was sent. allOf: - $ref: '#/components/schemas/StorefrontMediaBuyGoal' reporting: $ref: '#/components/schemas/StorefrontMediaBuyReportingState' creative: type: object properties: state: nullable: true type: string enum: - pending - attached - failed attachedCount: nullable: true type: integer minimum: 0 maximum: 9007199254740991 failureReason: nullable: true type: string enum: - format_translation_failed - source_rejected - delivery_failed required: - state - attachedCount - failureReason additionalProperties: false description: >- Creative readiness at list grain. A failed state includes a safe reason category so the seller can see whether the buyer, source, or platform must act. Null means no creative is attached or this source contract did not report creative state. openWork: type: object properties: count: type: integer minimum: 0 maximum: 9007199254740991 actionableCount: type: integer minimum: 0 maximum: 9007199254740991 blockedCount: type: integer minimum: 0 maximum: 9007199254740991 sourceIds: type: array items: type: string workItemIds: type: array items: type: string required: - count - actionableCount - blockedCount - sourceIds - workItemIds additionalProperties: false description: Open modular-source work correlated by this exact media-buy id. nextAction: type: object properties: owner: type: string enum: - seller - buyer - source - platform - none label: type: string required: - owner - label additionalProperties: false description: >- The current owner and action. `none` is an explicit no-action state, never an omitted inference. status: $ref: '#/components/schemas/SellerMediaBuyStatus' sourceStatus: nullable: true description: >- The raw upstream status as persisted (route leg rollup or source status string). Null before anything was sent. type: string settlementMethod: nullable: true description: >- The settlement method recorded for this booking: interchange means consolidated billing; seller means direct billing. Normal Seller Accounts—including third-party sales-agent and Agent-supplied (finished-product) sources—are consolidated-billing today. Direct billing for Seller Accounts is not yet configurable; seller currently appears only for official sales-adapter buys already settled under a downstream platform agreement. Null only for historical or upstream rows whose method was not recorded. type: string enum: - interchange - seller pendingReason: nullable: true description: >- Why the buy is not delivering yet (most-blocking leg), when derivable. Same vocabulary the buyer sees — one shared enum, never a status. allOf: - $ref: '#/components/schemas/MediaBuyPendingReason' pendingSince: nullable: true description: When the current wait began, when 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: nullable: true description: >- Structured error code of the latest failed exchange for this buy (ledger vocabulary, e.g. `unknown_product_ids`). Null when the latest exchange did not fail. type: string forwardOutcome: $ref: '#/components/schemas/SellerForwardOutcome' flightStart: nullable: true description: Flight start ("asap" or ISO 8601) when known. type: string flightEnd: nullable: true description: Flight end (ISO 8601) when known. type: string sourceCount: type: integer minimum: 0 maximum: 9007199254740991 description: >- Number of source legs this buy fans out to (1 for source-managed buys). esaId: nullable: true description: >- Ad server source connection id for source-managed buys; null for routed. The wire field remains `esaId` for API compatibility. type: string createdAt: nullable: true description: When the buy was received/created, when 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))$ forwardedAt: nullable: true description: >- When the buy was first successfully sent to a source. Null when nothing reached a source. 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 - kind - buyer - advertiser - operator - commercial - delivery - adServerDelivery - attention - goal - reporting - creative - openWork - nextAction - status - sourceStatus - settlementMethod - pendingReason - pendingSince - errorCode - forwardOutcome - flightStart - flightEnd - sourceCount - esaId - createdAt - forwardedAt additionalProperties: false description: One buy on the storefront, at the seller list grain. ApiError: type: object properties: code: type: string description: Machine-readable error code message: type: string description: Human-readable error message field: description: Field path associated with the error type: string details: description: Additional error context type: object additionalProperties: {} required: - code - message additionalProperties: false description: Structured error object StorefrontMediaBuyDelivery: type: object properties: impressions: type: number minimum: 0 spend: type: number minimum: 0 description: >- Seller-reported net spend. For a routed buy this comes from the storefront reporting pipeline, which provides no delivery currency at this projection grain; for a source-managed buy it is the ad server's own delivered spend, denominated in `commercial.currency`. clicks: nullable: true type: integer minimum: 0 maximum: 9007199254740991 views: nullable: true description: >- Content views as the source counts them (the CPV unit). This is NOT a count of viewable impressions and must not be divided by impressions to get a viewability rate. type: integer minimum: 0 maximum: 9007199254740991 completedViews: nullable: true type: integer minimum: 0 maximum: 9007199254740991 conversions: nullable: true type: integer minimum: 0 maximum: 9007199254740991 leads: nullable: true type: integer minimum: 0 maximum: 9007199254740991 pacingAgainstBookedBudget: nullable: true description: >- Delivered seller-reported spend divided by this buy's seller-visible booked budget. Null when no positive seller-visible booked budget is recorded (a missing, zero or negative budget has no ratio), and on `delivery` also null until every routed source has reported through the same day, since the budget covers the whole buy. It does not depend on the flight window. On its own this says nothing about whether the buy is on schedule — read `pace`. type: number minimum: 0 pace: nullable: true description: >- Delivered spend measured against how much of the flight has run, which is the only reading that separates a buy early in a long flight from one that will finish undelivered. This read sums the buy's whole reporting history, so `measuredFraction` equals `flightElapsed`. Null when this buy has no flight window recorded to measure against, and null until every source the buy was routed to has reported, all through the same day — a total that is part of the buy, or complete to different days on different sources, measures as underdelivery nobody reported. allOf: - $ref: '#/components/schemas/DeliveryPace' sourcesReported: type: integer minimum: 0 maximum: 9007199254740991 description: >- How many of this buy's routed sources are in these figures. Below `sourcesRouted` while a source has not sent its first report: the totals are real but they are only part of the buy, so `pace` and `pacingAgainstBookedBudget` are withheld until every source is in. sourcesRouted: type: integer minimum: 0 maximum: 9007199254740991 description: >- How many sources this buy was forwarded to. Compare with `sourcesReported` to see whether these figures cover the whole buy. lastDeliveryDate: type: string pattern: ^\d{4}-\d{2}-\d{2}$ description: >- Most recent UTC reporting day with a delivery record. This is a reporting-day date, not an invented event timestamp. required: - impressions - spend - clicks - views - completedViews - conversions - leads - pacingAgainstBookedBudget - pace - sourcesReported - sourcesRouted - lastDeliveryDate additionalProperties: false description: >- Delivery for one buy at the seller list grain, as the storefront reporting pipeline reported it. StorefrontMediaBuyAdServerDelivery: type: object properties: impressions: type: number minimum: 0 spend: type: number minimum: 0 description: >- Seller-reported net spend. For a routed buy this comes from the storefront reporting pipeline, which provides no delivery currency at this projection grain; for a source-managed buy it is the ad server's own delivered spend, denominated in `commercial.currency`. clicks: nullable: true type: integer minimum: 0 maximum: 9007199254740991 views: nullable: true description: >- Content views as the source counts them (the CPV unit). This is NOT a count of viewable impressions and must not be divided by impressions to get a viewability rate. type: integer minimum: 0 maximum: 9007199254740991 completedViews: nullable: true type: integer minimum: 0 maximum: 9007199254740991 conversions: nullable: true type: integer minimum: 0 maximum: 9007199254740991 leads: nullable: true type: integer minimum: 0 maximum: 9007199254740991 pacingAgainstBookedBudget: nullable: true description: >- Delivered seller-reported spend divided by this buy's seller-visible booked budget. Null when no positive seller-visible booked budget is recorded (a missing, zero or negative budget has no ratio), and on `delivery` also null until every routed source has reported through the same day, since the budget covers the whole buy. It does not depend on the flight window. On its own this says nothing about whether the buy is on schedule — read `pace`. type: number minimum: 0 pace: nullable: true description: >- Delivered spend measured against how much of the flight has run, which is the only reading that separates a buy early in a long flight from one that will finish undelivered. This read sums the buy's whole reporting history, so `measuredFraction` equals `flightElapsed`. Null when this buy has no flight window recorded to measure against, and null until every source the buy was routed to has reported, all through the same day — a total that is part of the buy, or complete to different days on different sources, measures as underdelivery nobody reported. allOf: - $ref: '#/components/schemas/DeliveryPace' required: - impressions - spend - clicks - views - completedViews - conversions - leads - pacingAgainstBookedBudget - pace additionalProperties: false description: >- The managing ad server's own running total for a source-managed buy. It names no reporting day. StorefrontMediaBuyAttention: type: object properties: tier: type: string enum: - money_at_risk - waiting_on_you - goal_behind - on_track description: >- How this buy ranks for the seller's attention: money the flight will not deliver, then work waiting on the seller, then a goal being missed, then everything else. moneyAtRisk: nullable: true description: >- What the flight will not deliver at the current rate, in `commercial.currency`: the booked budget minus the total spend this rate projects over the whole flight. It is NOT the shortfall accrued so far — half way through a 6,000 flight having spent 1,000, the hole to date is 2,000 and the money at risk is 4,000. Null when there is no pace to project from. type: number shareAtRisk: nullable: true description: >- `moneyAtRisk` as a share of the booked budget, 0 to 1. This is what `sort=attention` orders by, because a storefront can hold buys in different currencies and this ordering carries no exchange rate: a raw 10,000 JPY hole would otherwise outrank a 500 USD one. Null whenever `moneyAtRisk` is. type: number flags: type: array items: type: object properties: family: type: string enum: - task - delivery - goal level: type: string enum: - critical - attention - pending description: >- `critical` = the flight is running and the promise is not being kept (red). `attention` = worth acting on, promise intact (yellow). `pending` = not failure — the flight has not started, or the evidence does not support a verdict yet (neutral). label: type: string description: >- One seller-facing sentence naming the problem. Never a bare state word; a colour without a reason teaches sellers to ignore the colour. required: - family - level - label additionalProperties: false description: >- Everything that needs the seller on this buy, at most one per family. Empty when nothing does. required: - tier - moneyAtRisk - shareAtRisk - flags additionalProperties: false description: >- What needs the seller on one buy, and how loudly — the operations home's ranking and flags. StorefrontMediaBuyGoal: type: object properties: goal: nullable: true description: >- The buyer's goal being judged: the commitment's asked goal, else the campaign's primary goal. Null when only a fixed outcome price is on record. type: object properties: kind: type: string enum: - metric - event subject: type: string description: >- The metric name for a metric goal; the event type(s) joined with | for an event goal. eventTypes: type: array items: type: string target: nullable: true allOf: - $ref: '#/components/schemas/GoalProgressTarget' required: - kind - subject - eventTypes - target additionalProperties: false askedTarget: nullable: true description: The target the buyer asked for, when the goal carries one. allOf: - $ref: '#/components/schemas/GoalProgressTarget' answeredTarget: nullable: true description: >- The cost or return the seller's terms commit or aim at, from the media buy's goal commitment. allOf: - $ref: '#/components/schemas/GoalProgressTarget' commitment: nullable: true description: >- The commitment kind on the media buy, or the weakest across a campaign; null when no buy carries one. type: string enum: - guaranteed - best_effort - report_only commitmentSource: nullable: true description: >- Where a media buy commitment came from; null at campaign level, where buys may differ. type: string enum: - proposal - campaign actual: nullable: true description: >- The achieved cost per unit (per thousand for impressions), rate over the metric's own denominator, or volume for the goal's metric, computed from the same delivery this response reports. Null when the metric was not reported or has no observations. type: object properties: kind: type: string enum: - cost_per - threshold_rate - volume value: type: number unit: type: string enum: - impressions - clicks - views - completedViews - conversions - leads - viewableImpressions units: type: number minimum: 0 denominatorUnits: nullable: true description: >- What a threshold_rate divided by: measurable impressions for a viewable rate, impressions for every other rate. Null for a cost or a volume. type: number minimum: 0 perUnits: anyOf: - type: number enum: - 1 - type: number enum: - 1000 description: >- How many units a cost_per value prices: 1000 for impressions (a price per thousand, like CPM), 1 for every other unit. currency: nullable: true type: string required: - kind - value - unit - units - denominatorUnits - perUnits - currency additionalProperties: false verdict: nullable: true description: >- How delivery compares with the target. Null whenever the evidence does not support a verdict; see verdictWithheld. type: string enum: - on_track - behind - beat judgedAgainst: nullable: true description: >- Which target the verdict compares against: the buyer's asked target, or the seller's answered price when the buyer stated none. type: string enum: - asked - answered verdictWithheld: nullable: true description: >- Why there is no verdict. metric_unsupported covers metrics delivery does not carry (reach, attention), event goals other than lead-only ones and return-on-ad-spend targets, which need event-scoped counts this surface does not have. Too few observations means the metric is real but below the minimum count that makes a comparison meaningful. type: string enum: - no_goal - no_target - metric_unsupported - metric_not_reported - too_few_observations basis: nullable: true description: Who counted the number. Delivery on this surface is seller reported. type: object properties: kind: type: string enum: - seller_attested required: - kind additionalProperties: false freshness: type: object properties: dataThrough: nullable: true type: string reportingPeriodEnd: nullable: true type: string nextExpectedAt: nullable: true type: string notificationType: nullable: true type: string sequenceNumber: nullable: true type: number awaitingLaterReport: type: boolean missingMetrics: type: array items: type: string required: - dataThrough - reportingPeriodEnd - nextExpectedAt - notificationType - sequenceNumber - awaitingLaterReport - missingMetrics additionalProperties: false optimizedBy: nullable: true description: >- Who acts on the goal, for a buy an ad server manages. Read `optimizedBy.actor`, never `optimizedBy` itself: this is an object, not the enum. Null for a routed buy — it went to a third party whose optimization this storefront cannot see — null when the ad server did not answer, which is not evidence either way, and null for an ad-server buy whose id several buyers on this storefront hold, where no buyer can be named for it. type: object properties: actor: type: string enum: - ad_server - seller description: >- `ad_server` = the managing ad server optimizes towards this goal itself. `seller` = nothing automatic acts on it, so the seller's ad operations own it by hand. detail: nullable: true type: string required: - actor - detail additionalProperties: false required: - goal - askedTarget - answeredTarget - commitment - commitmentSource - actual - verdict - judgedAgainst - verdictWithheld - basis - freshness - optimizedBy additionalProperties: false description: >- How this buy is doing against the buyer's goal, at the seller list grain. StorefrontMediaBuyReportingState: nullable: true description: >- Whether delivery for this buy can be expected at all. `reported` = delivery exists. `awaiting_first_report` = the source can report and has not yet. `blocked` = the source cannot report at all, so no amount of waiting will produce delivery, and `detail` says what is in the way. Null when the reporting state could not be established (an unreachable source, or a source that never answered the question; see the response `warnings`) — deliberately not reported as "awaiting", which would assert something this read cannot see. oneOf: - type: object properties: state: type: string enum: - reported detail: type: string nullable: true enum: - null required: - state - detail additionalProperties: false - type: object properties: state: type: string enum: - awaiting_first_report detail: type: string nullable: true enum: - null required: - state - detail additionalProperties: false - type: object properties: state: type: string enum: - blocked detail: type: string description: >- Seller-facing explanation naming the source and what it is waiting on. Always present on this state: a blocked source with no reason is a dead end the seller cannot act on. required: - state - detail additionalProperties: false type: object MediaBuyPendingReason: 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 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. SellerForwardOutcome: type: string enum: - not_forwarded - all_completed - all_submitted - partial - failed description: >- How far forwarding to the underlying source(s) got: not_forwarded (nothing dispatched yet), all_completed (every source accepted inline), all_submitted (every source accepted asynchronously and is still finishing acceptance), partial (some sources accepted, some did not), failed (dispatch attempted, no source accepted). DeliveryPace: type: object properties: flightElapsed: nullable: true description: >- Fraction of the WHOLE flight elapsed at the measured instant, 0 to 1. This says where the buy is in its life; it is not what expectedSpend is computed from on a windowed read. type: number measuredFraction: nullable: true description: >- Fraction of the flight the reported spend actually covers. Equal to flightElapsed when the read covers the buy's whole life, smaller when it covers a selected window — and it is this, not flightElapsed, that expectedSpend and the verdict are measured over, so both sides of the ratio always describe the same interval. type: number expectedSpend: nullable: true description: >- The spend an even pace across the flight expects over the interval the reported spend covers. type: number actualSpend: nullable: true description: The delivered spend the expectation is compared against. type: number ratio: nullable: true description: >- actualSpend divided by expectedSpend; 1 sits exactly on the even-pace line. type: number spendPerDay: nullable: true description: >- Delivered spend per day of the measured interval — the number a "$200 a day" ask names. type: number budgetPerDay: nullable: true description: The daily rate an even pace across the whole flight implies. type: number currency: nullable: true type: string verdict: nullable: true description: >- How delivered spend compares with the even-pace line. Null whenever the evidence does not support a verdict; see verdictWithheld. `ahead` is neither praise nor alarm — it means the flight will exhaust early at this rate. type: string enum: - on_pace - behind - ahead verdictWithheld: nullable: true description: >- Why there is no pace verdict: no booked budget, no usable flight window, the flight has not started, the reporting window you asked for covers none of the flight (reading a recent window of a flight that ended months ago), the reported spend covers too little of the flight for the ratio to mean anything, or no delivery has been reported. type: string enum: - no_budget - no_flight - flight_not_started - window_outside_flight - too_short_a_window - spend_not_reported required: - flightElapsed - measuredFraction - expectedSpend - actualSpend - ratio - spendPerDay - budgetPerDay - currency - verdict - verdictWithheld additionalProperties: false description: >- Delivered spend measured against how much of the buy's flight has run, rather than against its budget alone. GoalProgressTarget: oneOf: - type: object properties: kind: type: string enum: - cost_per value: type: number required: - kind - value additionalProperties: false - type: object properties: kind: type: string enum: - threshold_rate value: type: number required: - kind - value additionalProperties: false - type: object properties: kind: type: string enum: - per_ad_spend value: type: number required: - kind - value additionalProperties: false - type: object properties: kind: type: string enum: - maximize_value required: - kind additionalProperties: false description: >- A goal target: a cost per unit, a minimum rate per impression, a minimum return on ad spend, or maximise with no number. type: object securitySchemes: bearerAuth: type: http scheme: bearer description: API key or access token ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.