The Trade Desk | Alli Documentation

Overview

This datasource utilizes the Trade Desk API to pull information from the Trade Desk UI.

Vendor/Partner	The Trade Desk
Version	`v3`
API Documentation	https://api.thetradedesk.com/v3/portal/api/doc/ApiOverview#changes-and-updates
Sunset Date	None as of January 2025 API Activity Log
Channel(s)	Programmatic
Refresh Time (CST)	6am
Default backfill	1 day
Alli Data Library

Getting Started

Because of the way The Trade Desk's API functions, the report that we want to pull using the API, must first be created in The Trade Desk's My Reports app at https://desk.thetradedesk.com/MyReports.

Create a report in the Trade Desk’s My Reports app.
Click the +TSV/CSV Report button in the My Reports page and create an New Custom Text Report.

Report Content Selections:

Type of report you are pulling into Alli Data.
Fields (ie. Dimensions) and Metrics that will be included in the report.
Report filter (ie, the advertisers, campaigns, ad groups that should be included in the report).
Date range.
File format (use CSV when possible).
Recurrence schedule (ie. How often the report should run).
Generated schedule name.

Required Authorization

Using an existing authorization

The Trade Desk uses our enhanced authentication system, if your client was already set up with Trade Desk once, you should be able to select it from the drop-down menu when creating a new datasource or editing an existing one.

Creating a new authorization

If your client does not have an authorization set up, you need to create a new authorization.

Please note when creating new authorizations, if you want to allow other users to use this authorization, you need to Save then click on the cog symbol next to your new authorization and modify the ACCESS LEVEL

Create a new Trade Desk datasource.
Click on New Authorization then Save & Authorize.
Fill out the auth form.

API Username and API Password

The API username and password for each specific partner can be obtained from your Trade Desk representative and are required for the remaining steps in this guide. These credentials are not necessarily the same that are used to create reports in the My Reports application.

Long-Lived Token (Optional)

The long-lived token for each specific partner can be obtained from your Trade Desk representative.

When filling out the authentication form, provide either:

API Username and API Password or
Long-lived Token

You do not need to enter both.

Partner ID

Input the ID for the Trade Desk partner to be pulled into Alli.

Then click Save at the bottom of the form once completed.

Datasource Configuration

Advertiser Name

After filling in the Datasource Settings above and clicking the Next button, the Advertiser Name selection menu will populate in the Additional Configuration Needed panel based on the advertisers included in the report created in My Reports.

Select any advertiser that appears within the report you created in step 1 above.
Use the Report Name Filter input box to optionally refine the results that will appear in the My Report Name selection dropdown. Then click the Next button.

As there can be a large number of report results, your report may not appear in the selection menu unless you refine the list using the Report Name Filter input box in this step.

3. After the page reloads, choose your report in the My Report Name selection menu. Reports that were created as .xlsx, will not show up in the results.

🚨 While generating the My Report Name dropdown list, the site may become unresponsive for a period of time. 🚨

The Trade Desk API can be very slow to return a list of reports. For that reason, the configuration page can take some time to load (~1 minute or more ⏳) after selecting an advertiser from the selection dropdown and clicking the Next button.

Define your Data

Unfortunately, since the Trade Desk API does not allow you to create reports on the fly, it is also not aware of the columns (dimensions and metrics) that are included in the report. As a result, you will need to use the manual Dimension/Metric picker to match the report that you created in the Trade Desk's My Report UI.

Select the report's columns as dimensions and metrics using the manual report builder.

You can download your report as a .csv file and drop it on to the Manual picker to auto-generate the report's columns. You should still take a minute to verify the auto-generated schema, as misconfigured dimensions and metrics can cause errors in the data and metric inflation. If you need help, here is a guide.

The timeframe of the data included in the report is set within the My Reports UI, so there is no date picker available.

If you need to backfill data, you should create your report as non-recurring, and include all the date ranges that you need in that one report.

Press Load Data to manually pull the most recently completed report available from the Trade Desk.

Dimensions

Name	ID	Type	Description
First-party Data ID	`first_party_data_id`	number	The numeric ID of the data segment within your first-party data
Third-party Data Brand	`third_party_data_brand`	string	The brand of the data segment
Third-party Data Brand ID	`third_party_data_brand_id`	number	ID of the data provider's brand
Third-party Data Full Path	`third_party_data_full_path`	string	Full description path of the data For example: "purchase intent" > "food and drink" > "natural foods
Third-party Data ID	`third_party_data_id`	number	Numeric ID of the data segment within your third-party data
Ad Environment	`ad_environment`	string	Environment in which your ad is served (in-app, web, mobile-optimized web)
Ad Format	`ad_format`	string	Format of your creative (300x250, 728x90, 120x600, etc.)
Ad Group	`ad_group`	string	Naming convention of your ad group (known as a line item or package)
Ad Group ID	`ad_group_id`	string	ID with which your ad group is associated; can be located in the URL at the ad group level in a series of numbers and letters after "AdGroups/detail" For example: https ://desk.thetradede sk.com/AdGroups/ detail/h28dawj
Ad Group Integer ID	`ad_group_integer_id`	number	Numeric ID for your ad group
Ad Server Creative Placement ID	`ad_server_creative_placement_id`	number	ID that your ad server associates with the creative
Ad Server Name	`ad_server_name`	string	Name of ad server if served by a third party
Advertiser	`advertiser`	string	Naming convention of your advertiser
Advertiser Currency Code	`advertiser_currency_code`	string	Currency that your advertiser uses
Advertiser ID	`advertiser_id`	string	ID associated with your advertiser; can be located in the URL
Advertiser Integer ID	`advertiser_integer_id`	number	Numeric ID for your advertiser
App	`app`	string	Name of a mobile application (app)
Audience	`audience`	string	Naming convention of your audience
Audience ID	`audience_id`	string	ID with which your Audience is associated; within the DMP, can be located in the URL in a series of numbers and letters after "dataplatform/deta il”
Browser	`browser`	string	Browser type (Internet Explorer, Firefox, Chrome, Safari, etc.)
Campaign	`campaign`	string	Naming convention of your campaign
Campaign ID	`campaign_id`	string	ID with which your Campaign is associated; can be located in the URL in a series of numbers and letters after "campaign="
Campaign Integer ID	`campaign_integer_id`	number	Numeric ID for your campaign
Carrier ID	`carrier_id`	string	ID associated with a mobile carrier
Carrier Name	`carrier_name`	string	Name of a mobile carrier (Verizon, Sprint, AT&T, etc.)
Category Hierarchy	`category_hierarchy`	string	Root and tree of the category hierarchy targeted via category white list
Category ID	`category_id`	string	ID associated with site categories; found in the template tabs for bulk site uploads (web category, app category, DoubleVerify, Grapeshot, gumgum, Integral, Peer39)
Category Name	`category_name`	string	Name associated with a site category; found in the template tabs for bulk site uploads (web category, app category, DoubleVerify, Grapeshot, gumgum, Integral, Peer39)
City	`city`	string	City used in geolocation data
Conversion ID	`conversion_id`	string	Unique identifier that TTD assigns to a conversion
Conversion Order ID	`conversion_order_id`	string	Unique identifier with which your advertiser associates the conversion (e.g. booking confirmation number); not populated unless the user passes this back as a dynamic parameter
Conversion Time	`conversion_time`	string	Time of the conversion; by default, listed in the time zone selected for a report
Conversion Time (UTC)	`conversion_time_utc`	string	Time of the conversion in Coordinated Universal Time (UTC)
Country	`country`	string	Country used in geolocation data
Creative	`creative`	string	Naming convention of your creative
Creative ID	`creative_id`	string	ID associated with your creative, written as a series of letters and numbers (e.g. h3mrsbiq); can be found in the creative library and should be provided to Support during creative troubleshooting
Creative Integer ID	`creative_integer_id`	number	Numeric ID for your creative; can be found at the creative level under the "Integer ID" column
Cross Device	`cross_device`	string	Name of the cross-device vendor used (AdBrain, Tapad, Drawbridge, Crosswise)
Data Element	`data_element`	string	Name of the data element provided by a vendor (usually, this is the last part of the data path)
Date	`date`	date	Date
Deal ID	`deal_id`	string	Deal code provided by the supply vendor or publisher to provide access to a private marketplace deal; presented as a long string of letters and/or numbers
Device Make	`device_make`	string	Specific make of a device (HTC, Google, LG, Apple, Blackberry, Nokia, etc.)
Device Model	`device_model`	string	Specific model of a device (iPhone 4, iPad 4s, Galaxy Nexus, Lumia 820, etc.)
Device Type	`device_type`	string	Specific type of a device (PC,Tablet, Mobile, Roku, Other, etc.)
Event Time	`event_time`	string	Time where event (impression or click) occurred; listed in the selected time zone
Event Time (UTC)	`event_time_utc`	string	Time where event (impression or click) occurred; listed in UTC
Factual Proximity Design Name	`factual_proximity_design_name`	string	Name of the proximity design created in your factual account
Factual Proximity Design Name	`factual_proximity_targeting_code`	string	Targeting code of the proximity design created in your factual account
Fold	`fold`	string	Fold position (above, below, unknown)
Fold Bid Factor	`fold_bid_factor`	string	Bid factor of the fold position
Frequency	`frequency`	number	How frequently an ad was shown to a single user; "0" means that one ad was shown
Inventory Contract	`inventory_contract`	string	Naming convention of your inventory contract
Inventory Contract ID	`inventory_contract_id`	string	ID associated with your inventory contract
Language	`language`	string	Language of the browser (English, Spanish, Chinese, etc.)
Matched Fold Position	`matched_fold_position`	string	Fold position of matched content (above, below, unknown)
Matched Language Code	`matched_language_code`	string	ID associated with the language chosen for a browser, Grapeshot, or Peer39
Matched Site	`matched_site`	string	URL of a site within a whitelist
Matched Site List ID	`matched_site_list_id`	string	ID associated with the site list; presented as a string of numbers and letters in the URL within the "Site/App" list of the library
Matched Site List Name	`matched_site_list_name`	string	Name of the whitelist where sites were matched when targeted for easier whitelist management
Media Type	`media_type`	string	Type of media used (Display, Video, Native, Audio, etc.)
Metro	`metro`	string	Name of the designated market area (DMA)
Metro Code	`metro_code`	string	Code associated with the DMA
Monetary Value	`monetary_value`	string	Revenue; populated only if a dynamic parameter is applied in the static tag
Monetary Value Currency	`monetary_value_currency`	string	Currency associated with the monetary value, as determined by dynamic parameter
Operating System	`operating_system`	string	Specific operating system used (Windows 7, Windows 10, etc.)
Operating System Family	`operating_system_family`	string	Family into which the specific operating system falls (Windows, iOS, etc.)
Partner Currency Code	`partner_currency_code`	string	Currency chosen during partner setup
Partner ID	`partner_id`	string	ID associated with your partner
Partner Integer ID	`partner_integer_id`	number	Numeric ID associated with your partner
Partner Name	`partner_name`	string	Naming convention of your partner
Recency Group	`recency_group`	string	Name of the recency bucket used in reporting (e.g. 0-0.5 days)
Recency Group End (in minutes)	`recency_group_end_in_minutes`	string	End of the recency time frame being measured (720 minutes, 1440 minutes, etc.)
Recency Group Start (in minutes)	`recency_group_start_in_minutes`	string	Beginning of the recency time frame being measured (zero minutes, 720 minutes, etc.)
Referrer URL	`referrer_url`	string	URL where a pixel was placed and fired
Region	`region`	string	Region used in geolocation data
Rendering Context	`rendering_context`	string	Environment in which an ad is rendered (in-app, mobile-optimized web, web, etc.)
Report Hour	`report_hour`	string	Customized reporting hour; listed in selected time zone
Report Hour (UTC)	`report_hour_utc`	string	Standard Trade Desk reporting hour; listed in UTC
Site	`site`	string	Domain URL
Site Bid Factor	`site_bid_factor`	string	Bid factor of your site list's domain set
Site List Name	`site_list_name`	string	Name of domain set
Supply Vendor	`supply_vendor`	string	Naming convention of your supply vendor
Supply Vendor Integer ID	`supply_vendor_integer_id`	string	ID for your supply vendor
Temperature Bucket End (in Celsius)	`temperature_bucket_end_in_celsius`	string	End temperature of a reporting bucket; listed in degrees Celsius (e.g. 10°C)
Temperature Bucket Name	`temperature_bucket_name`	string	Name of a temperature bucket (e.g. 10°C to 18°C) used in
Temperature Bucket Start (in Celsius)	`temperature_bucket_start_in_celsius`	string	Beginning temperature of reporting bucket; listed in degrees Celsius (e.g. 18°C)
Time Zone	`time_zone`	string	Time zone chosen for reporting (EST, UTC, etc.)
Tracking Tag ID	`tracking_tag_id`	string	Unique ID that is assigned to a tracking tag within The Trade Desk platform
Tracking Tag ID (Household)	`tracking_tag_id_household`	string	Unique ID that is assigned to a Tracking Tag within The Trade Desk platform once a household extension is applied
Tracking Tag Name	`tracking_tag_name`	string	Naming convention of a tracking tag created in The Trade Desk platform
Tracking Tag Name (Household)	`tracking_tag_name_household`	string	Naming convention of a tracking tag with a household extension applied that is created in The Trade Desk platform
Tracking Tag Type	`tracking_tag_type`	string	Type of tracking tag; either retargeting or conversion
User Day Of Week	`user_day_of_week`	string	Current day of the week for the user
User Hour of Day	`user_hour_of_day`	string	Current hour of the day for the user (0-23)
User Hour of Week	`user_hour_of_week`	string	Current hour of the week for the user, from 0-167 hours
Video Playback Type	`video_playback_type`	string	Format of playback for a video; either click-to-play or autoplay
Whitelist Site	`whitelist_site`	string	URL of a site within a whitelist

Metrics

Name	ID	Type	Description
Player 25% Complete	`player_25_complete`	number	Number of player ads played through to the first quarter
Player 50% Complete	`player_50_complete`	number	Number of videos played through to the mid-point
Player 75% Complete	`player_75_complete`	number	Number of videos played through to the third quarter
Player Audible Event	`player_audible_event`	number	Number of video ads that were audible to the user when served
Player Close	`player_close`	number	Number of video ads closed by the user
Player Collapse	`player_collapse`	number	Number of video ads collapsed by the user
Player Completed Views	`player_completed_views`	number	Number of video ads watched through to completion
Player Engaged Views	`player_engaged_views`	number	Number of times the video ad was viewed to completion or for 30 seconds, whichever happens first
Player Errors	`player_errors`	number	Number of errors that occurred in the video ad
Player Expansion	`player_expansion`	number	Number of times a user expanded the video ad
Player Full Screen	`player_full_screen`	number	Number of times the video ad played in fullscreen mode; only applicable for Windows Media Player
Player Invitation Accept	`player_invitation_accept`	number	Number of video ads during which a user activated a control that launched an additional portion of the linear creative
Player Mute	`player_mute`	number	Number of times a user muted a video ad
Player Pause	`player_pause`	number	Number of times a user paused a video ad; logged once per view
Player Playing Event	`player_playing_event`	number	Total number of player events (mute, pause, rewind, etc.)
Player Resume	`player_resume`	number	Number of times a user started the video ad after pausing it
Player Rewind	`player_rewind`	number	Number of times a user rewound the video ad
Player Skip	`player_skip`	number	Number of times a user skipped a skippable video ad
Player Starts	`player_starts`	number	Number of times that a video ad is started
Player Total Playing Seconds	`player_total_playing_seconds`	number	Number of seconds for which a video ad played
Player Unmute	`player_unmute`	number	Number of times that a user unmuted a video ad
Player Views	`player_views`	number	Number of times that a video ad was viewed
Smaller Player Impressions	`smaller_player_impressions`	number	Number of impressions served in a small player
Total Audible Seconds	`total_audible_seconds`	number	Number of seconds that a video ad played while audible
Total Click + View Conversions CPA	`total_click_view_conversions_cpa`	number	Cost / Total Click + View Conversions
% of Conversion Touches With Last Click or View Credit	`percent_of_conversion_touches_with_last_click_or_view_credit`	number	(All Last Click + View-through Conversions) / Conversion Touch
All Last Click + View CPA	`all_last_click_view_cpa`	number	Total Cost / (All Click + View-through Conversions)
Average Bid CPM	`average_bid_cpm`	number	(Bids / Bid Count) * 1000
Click + View CPA	`click_view_cpa`	number	Cost / (Click + View-through Conversion Count)
Click + View-through Conversions per Click	`click_view_through_conversions_per_click`	number	(Click Conversion Count + View-through Conversion Count) / Click Count
Click + View-through Conversions per Impression	`click_view_through_conversions_per_impression`	number	(Click Conversion Count + View-through Conversion Count) / Impression Count
Click Conversions CPA	`click_conversions_cpa`	number	Cost / Click Conversions
Click Conversions Rate	`click_conversions_rate`	number	Click Conversions / Clicks
Click Conversions per Click	`click_conversions_per_click`	number	Click Conversions / Clicks
Click Conversions per Impression	`click_conversions_per_impression`	number	Click Conversions / Impressions
Conversion Touch Revenue	`conversion_touch_revenue`	number	Revenue / Conversion Touch Count
Conversion Touches per Impression	`conversion_touches_per_impression`	number	Conversion Touch Count / Impression Count
Cost per Click (CPC)	`cost_per_click_cpc`		Cost / Clicks
Cost per Mille (CPM)	`cost_per_mille_cpm`	number	Cost per thousand impressions; Cost / (Impressions/1000)
Click through Rate (CTR)	`click_through_rate_ctr`	number	Clicks / Impressions
Player Completion Rate	`player_completion_rate`	number	Player Event Complete Count / Video Event Start Count
Sampled In-view Rate	`sampled_in_view_rate`	number	Sampled Viewed Impressions / Sampled Tracked Impressions
Total Click + View Conversion Rate	`total_click_view_conversion_rate`	number	(Click Conversion + View-through Conversion) / Impressions
View CPA	`view_cpa`	number	Cost / View-through Conversions
View-through Conversions per Click	`view_through_conversions_per_click`	number	View-through Conversions / Clicks
View-through Conversions per Impression	`view_through_conversions_per_impression`	number	View-through Conversions / Impressions
Viewable CPM (vCPM)	`viewable_cpm_vcpm`	number	CPM/Moat In-view Rate (the eCPM of viewable impressions)
Win Rate	`win_rate`	number	Impressions / Bids
All Last Click + View Conversions	`all_last_click_view_conversions`	number	All pixels' total number of conversions, as calculated by (Total Click + View-through Conversions)
Click Conversion	`click_conversion`	number	Number of conversions attributed to clicks
Click Conversions Revenue	`click_conversions_revenue`	number	Total revenue passed from a conversion pixel from click-through conversions
Conversion Touch	`conversion_touch`	number	Total number of impression touch points prior to conversion (inclusive of the conversions)
Total Click + View Conversions	`total_click_view_conversions`	number	Total number of conversions, from both click attribution conversion count and view attribution conversion count, in the relative reporting column number for the assigned tracking tags
View-through Conversion	`view_through_conversion`	number	Total number of conversions attributed to views
View-through Conversion Revenue	`view_through_conversion_revenue`	number	Total revenue passed from a conversion pixel from view-through conversions
Advertiser Cost	`advertiser_cost`	number	Partner Cost + Agency Fees (if applied in the campaign's fees and rates)
Charged Data Element Cost	`charged_data_element_cost`	number	Total cost charged to a specific data element
Fee Features Cost	`fee_features_cost`	number	Cost associated with ad-serving fees, including viewability tracking, Quality Alliance, Nielsen, weather targeting, and factual targeting
Margin	`margin`	number	Percentage of agency fees (if applied upon creation of campaign)
Media Cost	`media_cost`	number	Raw media cost (without data and fees applied)
Not-charged Data Element Cost	`not_charged_data_element_cost`	number	Total cost for data elements for which a single impression matched, but was not charged
Partner Cost	`partner_cost`	number	Media Cost + Data Cost + Fee Features + Tech Fees
Profit	`profit`	number	The margin in dollars (Partner Cost - Advertiser Cost)
Total Bid Amount	`total_bid_amount`	number	Sum of all bid amounts
Total Hypothetical Cost	`total_hypothetical_cost`	number	Advertiser Cost + Not-charged Data Impressions
TTD Cost	`ttd_cost`	number	Media Cost + Data Cost
Bid Count	`bid_count`	number	Total number of impressions bid on
Data Cost	`data_cost`	number	Cost associated with using third-party data segments, pre-bid brand safety/viewability targeting, and audience excluders
Bids	`bids`	number	Total number of bids
Charged Data Impressions	`charged_data_impressions`	number	Number of impressions that were mapped to each data segment (one impression can be mapped to multiple segments)
Hit Count	`hit_count`	number	Number of times a pixel fired from a tracking tag
Impressions	`impressions`	number	Total number of impressions won
In-banner Player Impressions	`in_banner_player_impressions`	number	Number of impressions served in banner
Large Player Impressions	`large_player_impressions`	number	Number of impressions served in a large player
Medium Player Impressions	`medium_player_impressions`	number	Number of impressions served in a medium player
Not-charged Data Impressions	`not_charged_data_impressions`	number	Total number of impressions for data elements that were matched on but not charged for
Impression Uniques	`impression_uniques`	number	Number of unique impressions served (unique device IDs, cookies, etc.); ten impressions served can have only one unique
Clicks	`clicks`	number	Total number of clicks
Creative Duration in Seconds	`creative_duration_in_seconds`	number	Amount of time a creative was in view, as determined by Moat viewability technology
Sampled Tracked Impressions	`sampled_tracked_impressions`	number	Number of impressions that were tracked by Moat viewability technology
Sampled Viewed Impressions	`sampled_viewed_impressions`	number	Number of impressions that were in view, as determined by Moat viewability technology
Companion Clicks	`companion_clicks`	number	Total number of clicks on the companion banner ad
Companion Impressions	`companion_impressions`	number	Total number of companion impressions served
Total Seconds in View	`total_seconds_in_view`	number	Number of seconds video has played in view, as determined by Moat viewability technology
Video In-view Event	`video_in_view_event`	number	Number of videos that were in-view, as determined by Moat viewability technology
Estimated Cost Per Completion (eCPCV)	`estimated_cost_per_completion_ecpcv`	number	Cost / Player Event Complete Count