Report execution and retrieval

IMPORTANT: Since you can create reports and define their templates only through the platform UI, be sure to complete these steps before using the API to retrieve reports. For details, see Rp - Reports in the Knowledge Portal.

The following diagram describes the process of retrieving reports using the My Reports API.

For details about retrieving template headers and scheduling reports, see Create and manage report schedules.

The following sections describe the report execution and retrieval steps illustrated at the bottom of the diagram.

Retrieve a report

To retrieve a report, complete the following steps.

Best practices

Here's what you need to know when using the report execution endpoints:

• Do not use partner endpoints to look up advertiser-level or partner-level reports.
• Do not include Content-Type headers in the request when downloading a report using a GET call with the Amazon S3 download URL.
• Verify that the link has not expired when you download a report using a GET call with the Amazon S3 download URL.
• Be sure to include a trailing period at the end of the URL.

TIP: You can download a code sample in Python that demonstrates the call patterns and best practices for this process and which you can use for testing in the sandbox environment.

Obtain a report download URL

Request

The following is an example of a POST /myreports/reportexecution/query/partners request with a {token} placeholder for your API token. It retrieves any partner-wide reports for the given date.

curl -H "Content-Type: application/json" -H "TTD-Auth:{token}" -X POST "https://api.thetradedesk.com/v3/myreports/reportexecution/query/partners" -d '{"PartnerIds": ["{Partnerid}"], "ExecutionStates": ["Complete”], "ExecutionSpansStartDate": "2019-06-20T00:00:00.4837693+00:00", PageStartIndex": 0, "PageSize": 10}'

Response

The following is an example of a POST /myreports/reportexecution/query/partners response with the report download URL.

{
    "Result":[
       {
          "ReportExecutionId":8247483,
          "ReportExecutionState":"Complete",
          "LastStateChangeUTC":"2019-06-21T03:32:33.073",
          "DisabledReason":null,
          "Timezone":"UTC",
          "ReportStartDateInclusive":"2019-06-07T00:00:00",
          "ReportEndDateExclusive":"2019-06-21T00:00:00",
          "ReportScheduleName":"Daily Report",
          "ReportDeliveries":[
             {
                "ReportDestination":"EmailedS3Link",
                "DeliveredPath":"thetradedesk-useast-hdreports/scheduled/2019/06/07/SpotX_NGL - Daily Report_18323/Daily Report/ Daily Report NGL_2019-06-07_8247483.tsv",
                "DeliveredUTC":"2019-06-21T03:32:33.027",
                "DownloadURL":"https://api.thetradedesk.com/v3/myreports/view/8247483/440916/1498163234?sig=l96E-guS636x8QccYWihundRc6Y2QhxprhkLBPtUv6k.", //Note the trailing period in the URL.
                "DownloadURLExpirationUTC":"2019-06-22T20:27:14.6448956Z"
             }
          ]
       }
    ],
    "ResultCount":1,
    "TotalFilteredCount":1
 }

Download report data

Request

The following is an example of a request to view report data. It uses the {token} placeholder for your API token and the download URL returned in the preceding response example.

curl -H "TTD-Auth:{token}" -X GET "https://api.thetradedesk.com/v3/myreports/view/8247483/440916/1498163234?sig=l96E-guS636x8QccYWihundRc6Y2QhxprhkLBPtUv6k."

The response to this call retrieves the contents of the report.

Report filtering

Based on the ReportExecutionStates, ReportScheduleIds, pagination, and other parameters that you specify in the My Reports execution endpoints, reports are filtered from the most general parameters like PageSize to more specific ones like ReportScheduleIds.

The following diagram illustrates the filtering process.

Report execution spans start and end dates

The following table provides guidelines and examples on setting the optional ExecutionSpansStartDate and ExecutionSpansEndDate values in the My Reports execution endpoints.

Note that "Reporting range" refers to the range of data included in a report.

The following table provides more examples, which assume that you have a daily report set to deliver one day’s worth of data and that today is August 7.