Deal measurement objects

NOTE: This reference provides all the necessary information to monitor your deal. For examples of how to query these objects, see Deal measurement queries.

Here's what you need to know about deal measurement:

The following sections lists all deal measurement objects grouped and sorted in hierarchical order.

DealMeasurements object

The DealMeasurements object represents the complete set of measurement data available for a deal.

Field Data Type Description
performanceMetrics Object Operational performance data that includes bid activity, spend, and delivery metrics. You can retrieve it as aggregated into totals or broken down by intervals. For field details, see PerformanceMetrics object.
qualityMetrics Object Quality assessment metrics compare deal performance to market benchmarks. For field details, see QualityMetrics object.
observedData Object Observed bidding and floor price data for the deal. For field details, see ObservedData object.
inventoryAdherence Decimal Inventory adherence measures how close the avails that come through the deal match what the selling party declared.
forecastedSpendUsd Decimal The forecasted spend amount for the deal in USD.
forecastedUnderspendPercent Decimal The forecasted underspend percentage for the deal.
forecastedUnderspendUsd Decimal The forecasted underspend amount for the deal in USD.

QualityMetrics object

The following table lists the query parameters you can use to filter and aggregate deal quality metrics in queries that support the where field.

Field Data Type Description
lookbackPeriod Enum Filter performance metrics data by a particular date range. For details, see Lookback period enumeration values.

The QualityMetrics object represents deal quality compared to market benchmarks. For an example query, see Quality metrics.

Field Data Type Description
startAt DateTime The start time of the quality measurement period.
addressability Object Addressability measures what proportion of inventory in the deal can be linked to a user or household ID in an identity graph. Higher addressability enables more advanced targeting and measurement. For field details, see QualityMetric object.
contributionToCampaignPerformance Object Contribution to campaign performance measures how much this deal is helping the buyer reach their KPIs compared to other targeted inventory. A high score means the deal is driving stronger results than the rest of the targeted inventory. For field details, see QualityMetric object.
dealQualityScore Object Deal quality score combines multiple indicators—price competitiveness, inventory uniqueness, addressability, and signal fidelity—to evaluate how the deal performs compared to marketplace benchmarks. Higher scores indicate better deal performance. For field details, see QualityMetric object.
inventoryExclusivity Object Inventory exclusivity measures the share of inventory reserved exclusively for the deal, rather than available through broader marketplace channels. For field details, see QualityMetric object.
priceCompetitiveness Object Price competitiveness compares the deal's pricing to market rates for similar inventory based on attributes like geography, channel, and publisher. Higher competitiveness means more attractive pricing. For field details, see QualityMetric object.
relevance Object Relevance shows how closely the users reachable through this deal match the buyer's ideal customer. This score is averaged across all ad groups buying this deal. For field details, see QualityMetric object.
signalFidelity Object Signal fidelity measures the detail and transparency the deal provides about its inventory. Higher signal fidelity allows for better optimization and measurement. For field details, see QualityMetric object.

QualityMetric object

Individual quality metrics in the QualityMetrics object follow a standard structure by comparing the observed performance of your deal to market benchmarks. For an example query, see Quality metrics.

Field Data Type Description
marketAverage Decimal The market average value that shows the performance of similar inventory.
observed Decimal The observed performance metric value for the deal.

PerformanceMetrics object

The PerformanceMetrics object provides operational data about deal performance and activity. Performance metrics can be queried with different aggregation options to return either total values or interval breakdowns. For an example query, see Performance metrics.

The following table lists the query parameters you can use to filter and aggregate deal performance data in queries that support the where field.

Field Data Type Description
aggregate Enum Controls how performance metrics are aggregated and returned. For values, see Measurement enumeration values.
includeContributingDeals Boolean Filter whether to include data from contributing deals.
NOTE: This value defaults to true.
performanceMetricsType Enum A type filter that can check whether the deal contains base terms, expanded terms, or overall (all) terms.
NOTE: This value defaults to OVERALL. For all values, see Measurement enumeration values.
dateTimeRange DateTime Filter performance metrics data by a particular date range. Only the date component is considered; time isn't relevant for the query.

The following table lists the PerformanceMetrics object response fields.

Field Data Type Description
availCount Long The number of available impression opportunities (bid requests) for the deal.
avgDailyAvailCount Long The average daily available impression opportunities for the deal.
avgDailySpendUsd Decimal The average daily spend amount for the deal in USD.
bidCount Long The number of bids placed on the deal.
bidRatePercent Decimal Percentage of available opportunities that received bids.
impressionCount Long The number of impressions delivered through the deal.
winRatePercent Decimal Percentage of bids that translated to impressions.
cpm Decimal The average cost per thousand impressions for the deal.
totalSpendUsd Decimal The total amount spent through the deal in USD.
startAt DateTime The start timestamp for the deal performance measurement period.

ObservedData object

The ObservedDataobject represents bidding terms and floor prices observed in your deal activity. For an example query, see Observed data.

The following table lists the query parameters you can use to filter and aggregate time series data in queries that support the where field.

Field Data Type Description
dateTimeRange DateTime Filter performance metrics data by a particular date range. Only the date component is considered; time isn't relevant for the query.

The following table lists the ObservedData object response fields.

Field Data Type Description
auctionTypes Object array The auction types and values observed for the deal. For details, see ObservedValueOf object. See also Auction type enumeration values.
biddingTerms Object array A list of bidding terms observed in the deal compared to marketplace averages. For field details, see ObservedBiddingTerm object.
floorPrices Object array A list of floor prices observed in the deal. For field details, see ObservedValueOf object.
inventoryComposition Object array A list of selection values observed in the deal. For field details, see ObservedInventoryComposition object.

ObservedBiddingTerm object

The ObservedBiddingTerm object represents how frequently specific bidding terms appear in your deal activity compared to marketplace averages.

Field Data Type Description
observedPercent Decimal The observed percent indicates how often this bid stream signal is included in the deal, expressed as a percentage of the deal's avails. For example, a value of 20 represents 20%.
marketPercent Decimal The market percent indicates how often this bid stream signal is included in the marketplace, expressed as a percentage of the total avails. For example, a value of 20 represents 20%.
biddingTerm Object The specific bidding term being measured. For field details, see BiddingTerm object.

BiddingTerm object

The BiddingTerm object represents a specific bidding term or signal.

Field Data Type Description
id ID The internal bidding term ID.
name String The name of the bidding term.

ObservedInventoryComposition object

The ObservedInventoryComposition object represents the inventory composition terms of the deal. For string enum values, see Inventory selection enumeration values.

NOTE: Each field of the ObservedInventoryComposition object has a nested ObservedValueOf object that compares the observed value with the deal terms. For object details, see ObservedValueOf object.

Field Data Type Description
adEnvironments String enum The environment where ads are shown, such as in-app or web.
adFormats Object The display format where ads are shown.
audioPodSeq Object The pod position instream for audio channels.
apps String The applications where ads are shown. Possible values can be Android package names or iOS bundle IDs.
audioFileType String enum The file format of the audio file.
audioSlotInPod Object The slot in the pod for audio channels.
audioStartDelay Object The start delay before the audio plays.
browsers Object The ID and name of the browser.
channels String The channels that the selling party sends in the deal.
NOTE: This is the IAB definition of a channel as a subset of a network, such as a channel for children. It's not an inventory channel, such as TV, audio, or display.
consumerGeos String enum The device geographical locales sent in the deal.
contentCategories String The categories of the websites where the ads are shown.
Valid values are IAB category IDs from the OpenRTB specification.
contentKeywords String The keywords related to the content where ads are shown.
contentLanguages String The languages of the content where the ads are shown.
contentRatings String The maturity rating for the content where the ads are shown.
deviceMakes String The manufacturers of the devices on which the ads are shown.
deviceTypes String The type of device on which the ads are shown.
episodes String The episode of the TV content where ads are shown.
feed String enum The feeds sent in this deal. Values are derived from the AdCOM Feed Types. Audio feed types are listed in the Inventory selection enumeration values.
genres String The genres of the TV content where ads are shown.
hasNativeAdRequest Boolean Set to true when the request comes from a native channel.
inventoryChannels String The name of the inventory channel where ads are shown, such as TV, audio, or display.
liveStream String enum Set to LIVE when the ad is shown alongside live content.
Possible values are the following:
  • LIVE
  • NOT_LIVE
  • UNKNOWN
mediaTypes Enum The media types of the inventory. For details, see Inventory selection enumeration values.
mobileCarriers String The mobile carriers used by the consumers viewing the ads.
money Object The payment information of the deal. For details, see Money object.
nativeOptionalAssetTypes String enum The optional asset types requested in a native ad request sent in the deal.
nativeRequiredAssetTypes String enum The required asset types requested in a native ad request sent in the deal.
networks String The list of networks with inventory in the deal.
operatingSystems String The operating systems of the devices on which the ads are shown.
placementIds String The ad placement IDs, such as GPIDs, that are sent in the deal.
plcmt String enum The type of placements in stream sent in the deal.
podSeq String enum The pod positions in stream sent in the deal.
productionQualities String enum The production qualities sent in the deal.
publisherCategories String The IAB category IDs of the site or app sent in the deal. These category IDs must match the taxonomy chosen in the deal.
publisherKeywords String The contextual keywords and phrases related to content sent in the deal.
publishers Object The known agent object of the publishers included in the deal.
seasons String The season of the TV content where ads are shown.
sellers Object The known agent object of the sellers included in the deal.
sellersJsonSellerIds Object The seller IDs that map to the sellers.json file of the supply vendor.
series String The name of the series where ads are shown.
sites String The website domains that sent in the deal.
skippability String enum The skippability of the inventory that the selling party includes from the deal.
Possible values are the following:
  • SKIPPABLE
  • NOT_SKIPPABLE
  • UNKNOWN
slotInPod String enum The order of slots in a given pod.
startDelay String enum The allowed delay time in seconds for the ads.
supplyVendorUserIdMappedToTDID Boolean Whether the supply vendor user ID is mapped to a TDID sent in the deal.
systemLanguages String The content browser languages that are sent in the deal.
titles String The titles of the shows where the ads are presented.
userIdTypeAvailable String enum The type of user identifier available in the bid request, such as TDID, device ID, or UID2.
venueTypes String The type of venue where the device showing the ad is placed.
videoDimensions Object The dimensions of the ads shown in the deal.
videoFileTypes String enum The file format of the video creative sent in the deal.
videoMinMaxBitRateInKbps Object The minimum and maximum bit rate of the video in kilobits per second sent in the deal.
videoMinMaxDurationInSeconds Object The minimum and maximum duration of the video in seconds sent in the deal.
videoPlayerSize String enum The size of the video player sent in the deal, such as small, medium, or large.
videoRequiredDurationsInSeconds Integer The required duration of the video creative in seconds sent in the deal.
videoSupportedApiFrameworks String enum The API framework supported by the video player sent in the deal, such as VPAID or MRAID.
videoSupportedVastVersions String enum The VAST protocol version supported by the video player sent in the deal.
wseat String The buyer seat IDs permitted to bid on the inventory in the deal.

ObservedValueOf object

The ObservedValueOf object represents the values observed in your deal activity with respect to its frequency.

Field Data Type Description
observedPercent Decimal The frequency of the field's value in the deal, expressed as a percentage.
value Inherited A list of values seen in the deal.
NOTE: This type matches the type of the value from the ObservedData object.

Money object

The Money object represents a monetary floor price and its currency.

Field Data Type Description
currency Object The currency supported for billing by The Trade Desk's platform. For field details, see Currency object.
amount Decimal The floor price amount, specified as a decimal. For example, 1.5 for $1.50.

Currency object

The Currency object represents the currency code and name of the currency.

Field Data Type Description
id String The three-letter currency code for the amount as specified in ISO 4217.
name String The name of the currency.

Measurement enumeration values

The following section contains the enumeration values used in the deal measurements object. These enumeration values can be used to change how performance metrics are filtered when querying for deal measurement data. For an example query, see Performance metrics.

Filter Enum Value Description
aggregate TOTAL Returns one set of aggregated values over the entire period/duration provided as input. For example, one set of aggregated values for a 7-day period.
aggregate TOTAL_BREAKDOWN_BY_INTERVAL Returns multiple sets of values, one per time interval determined by the date range. For example, 7 sets of daily values over a 7-day period, or hourly values depending on the date range and database support. Intervals are predefined based on the date range and available data.
performanceMetricsType OVERALL Returns all types of performance metrics.
performanceMetricsType BASE_TERMS Returns only the data that relates to the base terms of the deal.
performanceMetricsType EXPANDED_TERMS Returns only the data that relates to the expanded terms of the deal.

Lookback period enumeration values

The following table lists the time ranges that a deal can be filtered by. This value can be included in the lookback period of the aggregates filter. For details, see Deal queries.

NOTE: Each date starts from midnight UTC.

Enum Value Description
TODAY From the start of the current day up to now.
SINCE_YESTERDAY From the start of yesterday up to today.
LAST_SEVEN_DAYS The previous 7 days, including today.
LAST_FOURTEEN_DAYS The previous 14 days, including today.
LAST_THIRTY_DAYS The previous 30 days, including today.
MONTH_TO_DATE From the start of the current month up to today.
LIFETIME From the earliest available date up to now.