Optionaladcp_Release-precision AdCP version (VERSION.RELEASE, e.g. "3.0", "3.1", "3.1-beta"). On a request: the buyer's release pin — the seller validates against its supported_versions and returns VERSION_UNSUPPORTED on cross-major mismatch, or downshifts to the highest supported release within the same major. On a response: the release the seller actually served — clients SHOULD validate the response against that release's schema, not against their pin. Patches are not negotiated; surface them as build_version on capabilities for operational visibility. When omitted, falls back to adcp_major_version (deprecated) or server default. Buyers SHOULD emit both adcp_version and adcp_major_version through 3.x to remain compatible with sellers that only read the legacy field. NORMALIZATION: SDKs that read full-semver values from bundle metadata (e.g. ComplianceIndex.published_version = "3.1.0-beta.1") MUST normalize to release-precision ("3.1-beta.1") before emitting on the wire — meta-field values are NOT valid wire values.
Optionaladcp_DEPRECATED in favor of adcp_version (release-precision string). Servers MUST continue to honor this field through 3.x. Removed in 4.0. Original semantics: the AdCP major version the buyer's payloads conform to. Sellers validate against their supported major_versions and return VERSION_UNSUPPORTED if unsupported. When omitted, the seller assumes its highest supported version.
OptionalaccountOptionalmedia_Array of media buy IDs to get delivery data for
Optionalreporting_Exact immutable reporting revision to retrieve. This additive Reliable Reporting selector returns content bound to that revision, including its immutable row count, control totals, and content SHA-256. It is mutually exclusive with media-buy, date, metric, and breakdown selectors.
OptionalpaginationOptionalstatus_Filter by status. Can be a single status or array of statuses
Optionalstart_Inclusive start date for the reporting period (YYYY-MM-DD), as a calendar date in the reporting timezone: the reporting_capabilities.timezone of the products behind the in-scope packages. It is a UTC day only when that timezone is UTC. When omitted along with end_date, returns campaign lifetime data. Only accepted when the product's reporting_capabilities.date_range_support is 'date_range'. A date-bounded request whose in-scope packages span more than one reporting timezone MUST be rejected with VALIDATION_ERROR. The buyer narrows media_buy_ids to buys that share one reporting timezone, or omits both dates when a single buy's packages span reporting timezones.
Optionalend_Exclusive end date for the reporting period (YYYY-MM-DD), as a calendar date in the same reporting timezone as start_date. Must be later than start_date. When omitted along with start_date, returns campaign lifetime data. Only accepted when the product's reporting_capabilities.date_range_support is 'date_range'.
Optionalinclude_When true, include daily_breakdown arrays within each package in by_package. Useful for per-package pacing analysis and line-item monitoring. Omit or set false to reduce response size — package daily data can be large for multi-package buys over long flights.
Optionalrequested_Optional list of metrics to include in the response. When omitted, all available metrics are included (unchanged behavior). Applies to every metrics-bearing object in the response: totals, by_package, daily and window slices, and breakdown rows. impressions and spend are always included regardless of this list, except that a legacy or externally created mixed-currency buy MUST omit monetary and money-derived values from media-buy and window totals, MUST omit daily_breakdown, and MUST report monetary values only on currency-qualified package rows (including window package rows). Requesting a leaf metric identity returns its canonical nested carrier — e.g. requesting viewable_rate returns the viewability object, requesting quartile_75 returns quartile_data — never a flat duplicate. Metrics requested but not available for this buy are omitted from the response without error; contract accountability is unchanged — missing_metrics still reconciles against committed_metrics, but sellers MUST NOT list a metric in missing_metrics when its absence is solely due to this narrowing. Must be a subset of the product's reporting_capabilities.available_metrics; values outside the declared set are ignored. Subset evaluation follows the container-subsumption rule in enums/available-metric.json. Sort is evaluated before narrowing: excluding a metric from this list never triggers the sort_by fallback, and breakdown rows may be ordered by a metric absent from the narrowed payload — the applied-sort echo still names it. Same narrowing semantics as reporting_webhook.requested_metrics, with one shape difference: this field requires at least one entry when present (omit it entirely for full payloads), while the webhook field permits an empty array with the same meaning as omission.
Optionaltime_Optionalinclude_When true, the response includes media_buy_deliveries[].windows[] — an array of per-window delivery slices over the date range at the requested time_granularity. Ignored when time_granularity is omitted. Each window's payload mirrors what reporting_webhook would have delivered for the same window, enabling lossless GET-path recovery for buyers who missed webhook fires. Omit or set false to reduce response size when only cumulative aggregates are needed.
Optionalattribution_Attribution window to apply for conversion metrics. When provided, the seller returns conversion data using the requested lookback windows instead of their platform default. The seller echoes the applied window in the response. Sellers that do not support configurable windows ignore this field and return their default. Check get_adcp_capabilities conversion_tracking.attribution_windows for available options.
Optionalreporting_Request dimensional breakdowns in delivery reporting. Each key enables a specific breakdown dimension within by_package — include as an empty object (e.g., "device_type": {}) to activate with defaults. Omit entirely for no breakdowns (backward compatible). Unsupported dimensions are silently omitted from the response. For every requested dimension that the product declares supported, the seller MUST return the corresponding array (possibly empty) and its truncated flag. Metric-sorted dimensions also return their applied-sort echoes; demographic and property-grain arrays also return their suppressed flag. Spot uses aired_at ordering and has no sort echoes. Note: keyword, catalog_item, and creative breakdowns are returned automatically when the seller supports them; including their keys here is optional and upgrades them to this negotiated contract without changing the automatic default.
Optionalcatalog_item?: { limit?: number; sort_by?: SortMetric; sort_direction?: SortDirection }Request a negotiated catalog_item breakdown. Omitting this key preserves the automatic behavior — sellers return catalog_item rows at their discretion with no truncation contract. Including it (even as {}) makes the truncation disclosure and applied-sort echo binding.
Optionallimit?: numberMaximum number of catalog_item entries to return. When omitted, the seller returns its automatic default set.
Optionalsort_by?: SortMetricOptionalsort_direction?: SortDirectionOptionalcreative?: { limit?: number; sort_by?: SortMetric; sort_direction?: SortDirection }Request a negotiated creative breakdown. Omitting this key preserves the automatic behavior — sellers return creative rows at their discretion with no truncation contract. Including it (even as {}) makes the truncation disclosure and applied-sort echo binding.
Optionallimit?: numberMaximum number of creative entries to return. When omitted, the seller returns its automatic default set.
Optionalsort_by?: SortMetricOptionalsort_direction?: SortDirectionOptionalkeyword?: { limit?: number; sort_by?: SortMetric; sort_direction?: SortDirection }Request a negotiated keyword breakdown. Omitting this key preserves the automatic behavior — sellers return keyword rows at their discretion with no truncation contract. Including it (even as {}) makes the truncation disclosure and applied-sort echo binding.
Optionallimit?: numberMaximum number of keyword entries to return. When omitted, the seller returns its automatic default set.
Optionalsort_by?: SortMetricOptionalsort_direction?: SortDirectionOptionalgeo?: {Request geographic breakdown. Check reporting_capabilities.supports_geo_breakdown for available levels and systems.
Optionalsystem?: Optional classification system for metro or postal_area levels. Metro uses metro-system values (e.g., 'nielsen_dma'); native postal_area uses country-local postal-system values with country (e.g., country 'US', system 'zip'); deprecated legacy postal_area requests may use legacy-postal-system values such as 'us_zip'. Omit to request the level without selecting a specific system.
Optionalcountry?: stringISO 3166-1 alpha-2 country code. Required for native postal_area requests; omitted for legacy postal_area and non-postal geo requests.
Optionallimit?: numberMaximum number of geo entries to return. Defaults to 25. When truncated, by_geo_truncated is true in the response.
Optionalsort_by?: SortMetricOptionalsort_direction?: SortDirectionOptionaldevice_type?: {Request device type breakdown.
Optionallimit?: numberMaximum number of entries to return. When omitted, all entries are returned (the enum is small and bounded).
Optionalsort_by?: SortMetricOptionalsort_direction?: SortDirectionOptionalcursor?: stringOpaque cursor from a previous response's by_device_type_pagination to fetch the next page of a truncated by_device_type breakdown. Omit for the first page. limit, sort_by, and sort_direction MUST be repeated unchanged across paged requests for the same logical query.
Optionaldevice_platform?: {Request device platform breakdown.
Optionallimit?: numberMaximum number of entries to return. When omitted, all entries are returned (the enum is small and bounded).
Optionalsort_by?: SortMetricOptionalsort_direction?: SortDirectionOptionalcursor?: stringOpaque cursor from a previous response's by_device_platform_pagination to fetch the next page of a truncated by_device_platform breakdown. Omit for the first page. limit, sort_by, and sort_direction MUST be repeated unchanged across paged requests for the same logical query.
Optionalformat?: { limit?: number; sort_by?: SortMetric; sort_direction?: SortDirection }Request delivery broken down by canonical creative format kind. This dimension is negotiated on the GET path. Reporting webhook configuration does not negotiate or guarantee dimensional breakdowns, although a webhook payload may carry the same fields as an extension.
Optionallimit?: numberMaximum number of format rows to return. When omitted, all rows are returned because the canonical format-kind vocabulary is small and bounded.
Optionalsort_by?: SortMetricOptionalsort_direction?: SortDirectionOptionalaudience?: {Request audience segment breakdown.
Optionallimit?: numberMaximum number of entries to return. Defaults to 25.
Optionalsort_by?: SortMetricOptionalsort_direction?: SortDirectionOptionalcursor?: stringOpaque cursor from a previous response's by_audience_pagination to fetch the next page of a truncated by_audience breakdown. Omit for the first page. limit, sort_by, and sort_direction MUST be repeated unchanged across paged requests for the same logical query.
Optionaldemographic?: {Request delivery broken down by demographic. Check the product's reporting_capabilities.supports_demographic_breakdown independently from demographic_targeting. When age_ranges is present, every requested range MUST be exactly supported by exact_predicates or equal one of the declared enumerated_intervals; sellers MUST reject unsupported ranges with UNSUPPORTED_FEATURE rather than silently widen or narrow them.
Optionalage_ranges?: { min?: number; max?: number; include_unknown: boolean }[]Optional canonical age ranges to return as distinct rows. Copying an applied targeting predicate here requests aligned reporting only when the reporting capability supports that exact predicate. Omit to request the product's declared native demographic breakdown.
Optionallimit?: numberMaximum number of demographic entries to return. Defaults to 25.
Optionalsort_by?: SortMetricOptionalsort_direction?: SortDirectionOptionalspot?: { limit?: number }Request a spot-level as-run airing log for broadcast TV, radio, or other scheduled inventory. Rows are ordered by aired_at ascending. When limit is omitted, sellers SHOULD return the complete log for the requested reporting period.
Optionallimit?: numberOptional maximum number of spot rows to return. When the response is incomplete because of this limit or a seller-imposed maximum, by_spot_truncated is true.
Optionalplacement?: {Request placement breakdown.
Optionallimit?: numberMaximum number of entries to return. Defaults to 25.
Optionalsort_by?: SortMetricOptionalsort_direction?: SortDirectionOptionalcursor?: stringOpaque cursor from a previous response's by_placement_pagination to fetch the next page of a truncated by_placement breakdown. Omit for the first page. limit, sort_by, and sort_direction MUST be repeated unchanged across paged requests for the same logical query.
Optionalproperty?: DeliveryBreakdownControlsOptionalcollection?: DeliveryBreakdownControlsOptionalinstallment?: DeliveryBreakdownControlsOptionalcollection_property?: DeliveryBreakdownControlsOptionalinstallment_property?: DeliveryBreakdownControlsOptionalplacement_property?: DeliveryBreakdownControlsOptionalcontextOptionalext
Request parameters for retrieving comprehensive delivery metrics