Demand metric dictionary

Read each response's measurement basis, window, timezone and freshness fields before comparing it with another endpoint. The same screen can have inventory, issued opportunities, rendered starts, completed plays, audience observations and publisher reports with different counts.

Money, quantities and booking state

Field or familyUnit and grainInterpretation
budgetUsd, ownedBudgetUsd, partnerBudgetUsd, provider budget and reviewedSubtotalUsdUSD major units per plan or selected line setA budget or reviewed subtotal is not a charge receipt.
amountMinor / checkout reviewedAmountInteger minor units of the returned currencyCopy exactly from prepare. Do not assume every currency has two decimals.
Prepare amount, taxAmountMajor units of the returned buyer currencyRead with currency; USD-named fields retain USD units.
reviewedSelectionOpaque selection fingerprintBinds the reviewed inventory, flight, quantities and targeting; reuse unchanged for that checkout.
Impression goal / selected impressionsPurchased or requested quantity on the named lineA goal is not measured delivery.
ForecastEstimated capacity or audience for the requested inventory and flightDoes not reserve inventory or establish completion.
bookingState and line statesCurrent campaign and fulfillment stateA draft, checkout URL, accepted bid or pending owner IO is not live delivery.
partial_stop, pending owner stops, flight line resultsAction outcome per original lineKeep incomplete results visible. Requested dates are distinct from applied dates.

Campaign measurement

GET /openrtb/v2/buying/campaigns/{id}/delivery returns the same canonical measurement used by portal analytics and campaign reports.

Booked or paid buyer spend remains the native order/payment quantity. Completed-play event revenue is the recorded priced delivery fact. Creative-wrapper plays are a separate creative metric. A report can present these together without making them interchangeable or deriving every value from one event count.

Field or familyUnit and grainDenominator / missing behavior
measurement.delivery.playsDeduplicated billable completed plays in the measurement windowCompletion identity and billing eligibility define the count; never substitute a placement goal.
measurement.reach.screens_nDistinct observed screens across the whole windowDo not sum per-day distinct counts.
measurement.reach.devices_nDistinct observed device identifiers across the whole windowAn identifier count is separate from persons_n; missing measurement stays null.
measurement.reach.persons_nPerson reach when measured by its declared sourcenull when not measured.
Audience and attentionThe response's named measure, population and unitKeep audience estimates/observations separate from billable completed plays.
Pacing goal and delivered progressNative booked-line goal and reported progressCan have a different event basis and flight scope from windowed measurement.
Source reconciliationEach source's count and difference from canonical deliveryAudience daily plays and retained completion events use the requested window; placements and partner reports are flight-to-date. They are comparisons, not additional plays to add.
degraded_fieldsNames of unavailable optional measurementsOptional sections remain null; surviving billable delivery can remain available.

An explicit startDate/endDate or period wins. Dates normalize to whole UTC days, the end includes that UTC day and is capped at now. Without a window, a dated campaign uses its flight; an undated or future flight uses the reader default. The measurement window is capped at 400 days. Creative detail uses a separate 31-day window. Local creative dwell/daypart analysis uses screen timezone; unresolved timezone remains unresolved rather than being relabeled UTC.

DSP auction statistics

GET /openrtb/v2/stats describes the trailing 24 hours of auction rows carrying the authenticated seat. Read measured and stats.coverage first. matched_auctions counts matching auction rows; total_bids sums their recorded bid counts; total_wins counts rows with a recorded won result. avg_latency_ms is milliseconds and avg_cpm is the mean recorded auction CPM. This read does not return currency-separated quote distributions; use market benchmarks for those.

total_revenue is null: an auction CPM is a rate and does not establish settled spend. An absent seat cohort or unavailable auction store returns unmeasured metrics with its coverage reason, rather than a fabricated zero.

DSP delivery and proof

DSP summary, screen and time-series reports use the authenticated seat's canonical billable completed plays. total_impressions / impressions count plays; billable_quantity sums their recorded impression multipliers. avg_cpm is priced gross revenue × 1000 / priced billable quantity when that quantity is positive and the cohort has one currency; otherwise it is null. A mixed cohort's currency is null. hours_active counts distinct UTC completion-hour buckets, not elapsed online time. Completion reports have no issued-request denominator, so no_fill and fill_rate are null.

The creative report retains its separate existing creative-play rollup. plays counts recorded creative plays, play_seconds sums their duration in seconds, and unique_screens counts distinct recorded screens per creative/ad pair. Its lookback starts at the corresponding UTC rollup day. These wrapper creative plays are not interchangeable with billable completed plays. Unavailable report reads return 503.

Proof-of-play has grain billable_play_per_screen. duration_seconds is seconds; display_area_ratio is a ratio. Read verification_tier for signed, event-confirmed or partner-reported evidence. A signature is returned only when present. The proof interval is UTC [start_date,end_date), at most 400 days, capped at now. observed_latest_completed_at identifies the latest included completion, and queried_at identifies query time. The proof summary's GIVT pass rate describes the already eligible returned cohort, not every attempted play.

Issued-opportunity funnel

GET /openrtb/v2/analytics/funnel is seat-scoped to issued inbound prebid opportunities and their linked responses, selected starts and completions. Use UTC dates within the last 90 days; the end date includes that day through now. Cached reads can be up to five minutes old.

FieldGrain / unitRate definition
requestsIssued request/screen observationsNot global VAST traffic.
issued_impressionsIssued request/impression opportunitiesThe fill-rate denominator.
bids_receivedIssued requests with at least one accepted candidate responseThe compatibility name does not count every submitted or rejected bid.
accepted_bidsAccepted candidate bidsAdmission does not imply selection or payment.
renders_startedServer-selected starts linked to issued opportunitiesThe fill-rate numerator.
plays_completedCanonical completed plays linked to the same cohortThe start-to-complete numerator.
bid_rateRatio, rounded to three decimalsbids_received / requests.
fill_rateRatio, rounded to three decimalsrenders_started / issued_impressions.
start_to_completeRatio, rounded to three decimalsplays_completed / renders_started.
no_bids / no_accepted_responseClosed issued requests without an accepted responseRead alongside pending; an opportunity can still be open.
errorsUnmeasurednull.

The cohort is selected by opportunity issue time; linked starts and completions can arrive after the interval's end through query time. A zero denominator gives a null rate. Read coverage.issued_observations_from, prefix_unobserved and unobserved_prefix_end. A requested interval extending before recorded opportunities has unmeasured full-window funnel fields; observed_cohort still describes its measured portion. This is not reconstructed historical solicitation traffic.

Market intelligence

Market metrics have grain response_top_bid: one top-bid price per observed outbound response joined to the exact proxy attempt. Each currency remains separate. Country and region come from that observed attempt. market_overview uses the same filtered cohort as the detail rows.

FieldUnit / denominator
CPM p25, median, p75, avgPrice per thousand, in the row's currency; distribution of positive finite response-top-bid prices.
sample_sizeNumber of priced responses in the row's venue/currency/period group.
quoted_responsesDeduplicated joined responses, including unpriced responses.
priced_responsesJoined responses with positive finite top price and a recorded currency.
bid_volumeSum of response bid counts, not a count of completed plays.
observed_screensDistinct nonempty screen IDs in the filtered response cohort.
Category response_count and avg_cpmClassified priced responses and their mean top price per currency; classification coverage is returned.
avg_fill_rate, avg_completion_rate, daypart fill_rate, segment_premiumsnull: the quote cohort has no corresponding delivery denominator or premium baseline.
total_screens_sspnull: the response cohort does not measure total catalogue inventory.

Venue groups can overlap; do not add them as unique responses. days selects 1–90 periods of 24 completed UTC hours, ending at coverage.as_of (window_basis: completed_utc_hours). Market daily buckets and these seven dayparts use UTC:

DaypartUTC hours, start-inclusive / end-exclusive
early_morning05:00–08:00
morning08:00–11:00
midday11:00–14:00
afternoon14:00–17:00
evening17:00–20:00
night20:00–23:00
late_night23:00–05:00

coverage.window and as_of describe the read window; observed_last_response_at is the latest observed response in it. Cache lifetime is ten minutes. Every requested hour must have a complete measurement; the most recent completed hour must have refreshed within fifteen minutes. Historical hours refresh daily, and coverage.oldest_snapshot_at gives the oldest refresh start in this window. A missing required hour, a stale most recent hour or a store failure returns 503. A complete measured-empty window returns zero.

Data products and supplier reports

Data products keep their own named dataset grain, units, dimensions, watermark and entitlement. Supplier report counters retain their report basis and freshness. A missing observation stays null; an observed empty cohort can have count zero. Read the exact Data reference and Demand reference for the operation's fields.

Interaction and verification reports

Native interaction analytics count recorded interaction events, using the native advertisement owner or canonical screen access for scope. The QR report counts only qr_scan and qr_interaction in that ledger. These are distinct from instant-ad scan attribution, unique people, buyer purchases and completed plays. UTC hour/day/week/month buckets use reported event time; week uses Sunday-start %U numbering. The effective window retains 90 days. A complete matched set above 10,000 events returns 413 with narrowing guidance; it never returns truncated totals. Required read failures return 503. engagementRate stays null without a matching measured impression denominator.

The impression list returns at most 1,000 canonical ledger rows. summary.totalImpressions counts that list. Its retired legacy viewability summary returns null for viewableImpressions, viewabilityRate and avgViewableTime, with an empty compatibility detail array. OMSDK verification and other viewability readers retain their own measurement grain.

FEIN creative/venue observations roll up by category/brand, venue and UTC day; joined inference context is venue/day data. FEIN fill rate is recorded VAST fills / total_requests, as a fraction. OMSDK verification rates are percentages over its session population; its screen breakdown is capped at 100 screens. FEIN model status counts recorded gradient receipts by their canonical uploaded_at. These required source reads return 503 when unavailable, separately from a healthy empty result.