# 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 family | Unit and grain | Interpretation |
|---|---|---|
| `budgetUsd`, `ownedBudgetUsd`, `partnerBudgetUsd`, provider budget and `reviewedSubtotalUsd` | USD major units per plan or selected line set | A budget or reviewed subtotal is not a charge receipt. |
| `amountMinor` / checkout `reviewedAmount` | Integer minor units of the returned `currency` | Copy exactly from prepare. Do not assume every currency has two decimals. |
| Prepare `amount`, `taxAmount` | Major units of the returned buyer currency | Read with currency; USD-named fields retain USD units. |
| `reviewedSelection` | Opaque selection fingerprint | Binds the reviewed inventory, flight, quantities and targeting; reuse unchanged for that checkout. |
| Impression goal / selected impressions | Purchased or requested quantity on the named line | A goal is not measured delivery. |
| Forecast | Estimated capacity or audience for the requested inventory and flight | Does not reserve inventory or establish completion. |
| `bookingState` and line states | Current campaign and fulfillment state | A draft, checkout URL, accepted bid or pending owner IO is not live delivery. |
| `partial_stop`, pending owner stops, flight line results | Action outcome per original line | Keep 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 family | Unit and grain | Denominator / missing behavior |
|---|---|---|
| `measurement.delivery.plays` | Deduplicated billable completed plays in the measurement window | Completion identity and billing eligibility define the count; never substitute a placement goal. |
| `measurement.reach.screens_n` | Distinct observed screens across the whole window | Do not sum per-day distinct counts. |
| `measurement.reach.devices_n` | Distinct observed device identifiers across the whole window | An identifier count is separate from `persons_n`; missing measurement stays `null`. |
| `measurement.reach.persons_n` | Person reach when measured by its declared source | `null` when not measured. |
| Audience and attention | The response's named measure, population and unit | Keep audience estimates/observations separate from billable completed plays. |
| Pacing goal and delivered progress | Native booked-line goal and reported progress | Can have a different event basis and flight scope from windowed measurement. |
| Source reconciliation | Each source's count and difference from canonical delivery | Audience 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_fields` | Names of unavailable optional measurements | Optional 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.

| Field | Grain / unit | Rate definition |
|---|---|---|
| `requests` | Issued request/screen observations | Not global VAST traffic. |
| `issued_impressions` | Issued request/impression opportunities | The fill-rate denominator. |
| `bids_received` | Issued requests with at least one accepted candidate response | The compatibility name does not count every submitted or rejected bid. |
| `accepted_bids` | Accepted candidate bids | Admission does not imply selection or payment. |
| `renders_started` | Server-selected starts linked to issued opportunities | The fill-rate numerator. |
| `plays_completed` | Canonical completed plays linked to the same cohort | The start-to-complete numerator. |
| `bid_rate` | Ratio, rounded to three decimals | `bids_received / requests`. |
| `fill_rate` | Ratio, rounded to three decimals | `renders_started / issued_impressions`. |
| `start_to_complete` | Ratio, rounded to three decimals | `plays_completed / renders_started`. |
| `no_bids` / `no_accepted_response` | Closed issued requests without an accepted response | Read alongside `pending`; an opportunity can still be open. |
| `errors` | Unmeasured | `null`. |

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.

| Field | Unit / denominator |
|---|---|
| CPM `p25`, `median`, `p75`, `avg` | Price per thousand, in the row's `currency`; distribution of positive finite response-top-bid prices. |
| `sample_size` | Number of priced responses in the row's venue/currency/period group. |
| `quoted_responses` | Deduplicated joined responses, including unpriced responses. |
| `priced_responses` | Joined responses with positive finite top price and a recorded currency. |
| `bid_volume` | Sum of response bid counts, not a count of completed plays. |
| `observed_screens` | Distinct nonempty screen IDs in the filtered response cohort. |
| Category `response_count` and `avg_cpm` | Classified priced responses and their mean top price per currency; classification coverage is returned. |
| `avg_fill_rate`, `avg_completion_rate`, daypart `fill_rate`, `segment_premiums` | `null`: the quote cohort has no corresponding delivery denominator or premium baseline. |
| `total_screens_ssp` | `null`: 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:

| Daypart | UTC hours, start-inclusive / end-exclusive |
|---|---|
| `early_morning` | 05:00–08:00 |
| `morning` | 08:00–11:00 |
| `midday` | 11:00–14:00 |
| `afternoon` | 14:00–17:00 |
| `evening` | 17:00–20:00 |
| `night` | 20:00–23:00 |
| `late_night` | 23: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](https://api.trillboards.com/docs#data) and [Demand reference](https://api.trillboards.com/docs#demand) 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.
