Create Report Schedules

The Reports feature in the platform UI provides high-impact reporting on advertising campaigns by allowing you to customize and schedule your reports. You can either include or exclude metrics from the standard templates or build a template from scratch.

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

After you define your report templates in the platform UI, you can use the My Reports API to schedule reports programmatically for individual advertisers or for multiple advertisers under a partner, which is useful if you manage many advertisers.

For details on retrieving report data, see Report execution and retrieval.

What you need to know

Here's what you need to know about report schedules:

You can create and manage report schedules using the platform UI or API.
To use the My Reports API, you must generate an API token with a daily or weekly expiration and include it in your My Reports calls in the TTD-Auth header parameter. For details on generating short-lived and long-lived API tokens, see API token authentication.
Currently, there is a limit of 100 report schedules per partner API account.

Common tasks

The following table lists common report schedule managements tasks with links to the sections that provide additional information, if available.

Task	Description	Endpoint
Retrieve available report template facets	View the possible types, formats, and fields by which you can filter report templates.	GET /v3/myreports/reporttemplate/facets
Query report template headers	Retrieve report template headers using query filters, such as `ReportTemplateIds`, `NameContains`, or `CreatedByContains`.	POST /v3/myreports/reporttemplateheader/query
Retrieve conversion pixel names	Retrieve conversion pixel names if you want to add report columns for specific conversion pixels when creating a report schedule.	POST /v3/myreports/conversionpixelnames
Create a report schedule	Follow the provided best practices to create report schedules you need.	POST /v3/myreports/reportschedule
Retrieve available report schedule facets	View all facets of a report schedule, including date ranges, file formats, sorting fields, cadence, status, and other details.	GET /v3/myreports/reportschedule/facets
Query report schedules	Retrieve report schedules using query filters, such as `ReportScheduleIds`, `NameContains`, or `ShowOnlyRequestedByMe`.	POST /v3/myreports/reportschedule/query
Retrieve a report schedule for a given ID	Retrieve a specific report schedule by its ID.	GET /v3/myreports/reportschedule/{scheduleid}
Delete a report schedule for a given ID	To manage the report schedule quota (currently 100 schedules) assigned to your account, delete any outdated schedules by using their IDs.	DELETE /v3/myreports/reportschedule/{scheduleid}

Retrieve all available report template facets

To retrieve the possible types, formats, and fields by which you can filter report templates, use the GET /v3/myreports/reporttemplate/facets endpoint.

Request

The following is an example of a GET /v3/myreports/reporttemplate/facets request with a {token} placeholder for your API token.

curl -H "Content-Type: application/json" -H "TTD-Auth:{token}" -X GET "https://api.thetradedesk.com/v3/myreports/reporttemplate/facets"

Response

The following is an example of a GET /v3/myreports/reporttemplate/facets response with all available report template facets.

{
    "Types": [
        {
            "Value": "Standard",
            "DisplayName": "Standard"
        },
        {
            "Value": "Custom",
            "DisplayName": "Custom"
        }
    ],
    "Formats": [
        {
            "Value": "Text",
            "DisplayName": "Text"
        },
        {
            "Value": "Excel",
            "DisplayName": "Excel"
        }
    ],
    "SortingFields": [
        {
            "Value": "Name",
            "DisplayName": "Name"
        },
        {
            "Value": "CreatedBy",
            "DisplayName": "Created By"
        }
    ],
}

Query report template headers

To retrieve report template headers for specified query filters, use the POST /v3/myreports/reporttemplateheader/query endpoint.

TIP: The most commonly used filters are ReportTemplateIds, NameContains, and CreatedByContains.

Request

The following is an example of a POST /v3/myreports/reporttemplateheader/query request with a {token} placeholder for your API token and several filters.

curl -H "Content-Type: application/json" -H "TTD-Auth:{token}" -X POST "https://api.thetradedesk.com/v3/myreports/reporttemplateheader/query" -d '{"NameContains": "Adgroup Performance", "CreatedByContains": "System", "Format": "Text", "PageStartIndex": 0, "PageSize": 10}'

Response

The following is an example of a POST /v3/myreports/reporttemplateheader/query response with the report template headers that match the query filters specified in the request.

{
    "Result": [
        {
            "ReportTemplateId": 168005,
            "Name": "Adgroup Performance Report HD",
            "Type": "Standard",
            "Format": "Text",
            "CreatedByUserName": "Urszula Etheridge"
        }
    ],
    "ResultCount": 1
}

Retrieve conversion pixel names for report schedules

If you want to add report columns for specific conversion pixels when creating a report schedule, you may need to specify the names of the conversion pixels along with their tracking tag IDs. To retrieve a list of conversion pixel names, use the POST /v3/myreports/conversionpixelnames endpoint.

Request

The following is a JSON example of a POST /v3/myreports/conversionpixelnames request.

{
  "PartnerIds": [
    "partner123abc"
  ],
  "ReportTemplateId": 168005,
  "CrossDeviceAttributionModelId": null,
  "PageStartIndex": 0,
  "PageSize": 5
}

Response

The following is an example of a POST /v3/myreports/conversionpixelnames response with a list of conversion pixels, each with its advertiser ID, pixel name, tracking tag ID (ConversionType), and attribution model ID specified.

{
  "Result": [
    {
      "AdvertiserId": "adv890xyz",
      "ConversionPixelName": "Generic Inc Friends Conversion",
      "ConversionType": "abc123", // This is the tracking tag ID.
      "CrossDeviceAttributionModelId": "IdentityAlliance"
    },
    {
      "AdvertiserId": "adv890xyz",
      "ConversionPixelName": "Landing Page Visit",
      "ConversionType": "234def", // This is the tracking tag ID.
      "CrossDeviceAttributionModelId": "IdentityAlliance"
    },
    {
      "AdvertiserId": "adv890xyz",
      "ConversionPixelName": "Inferred Brand Impact",
      "ConversionType": "123abc", // This is the tracking tag ID.
      "CrossDeviceAttributionModelId": "IdentityAlliance"
    }
  ],
  "ResultCount": 3
}

Create a report schedule

To create a report schedule, use the POST /v3/myreports/reportschedule endpoint.

Best practices

Here's what you need to keep in mind when creating reports:

For the most efficient workflow, create partner-level schedules and create schedules with a single-day lookback window. This ensures that completed reports contain the final report data, which is never updated after the report is complete.
To retrieve all available data for a given date, create schedules with single-day lookback periods, but set the ScheduleStartDate field value to a date in the past.
To retrieve historical data, create a one-off schedule for a longer time frames, which you can set in the ReportDateRange field.
When setting your custom report start and end dates, be sure to select a valid data range. To get a full month's report on the first of the next month, set the StartDateInclusive and EndDateExclusive fields to span a full month. For details, see Best practices for custom report start and end dates.

Request

The following is a JSON example of a POST /v3/myreports/reportschedule request, which includes the conversion pixel names retrieved using the request example in the preceding section.

{
  "ReportScheduleName": "Adgroup Performance Report HD",
  "RequestedByUserName": "jane.doe@companyemail.com",
  "ReportTemplateId": 168005,
  "IsCompleted": true,
  "ReportScheduleStatus": "Disabled",
  "ReportFileFormat": "TSV",
  "PartnerFilters": [
    "partner123abc"
  ],
  "ReportDateRange": "LastXDays",
  "TimeZone": "UTC",
  "ReportDateFormat": "International",
  "ReportNumericFormat": "US",
  "IncludeHeaders": true,
  "LookbackDays": 1,
  "ReportFrequency": "Daily",
  "ConversionPixelNames": [
    {
      "AdvertiserId": "adv890xyz",
      "ConversionPixelName": "Generic Inc Friends Conversion",
      "ConversionType": "abc123", // This is the tracking tag ID.
      "CrossDeviceAttributionModelId": "IdentityAlliance"
    },
    {
      "AdvertiserId": "adv890xyz",
      "ConversionPixelName": "Landing Page Visit",
      "ConversionType": "234def", // This is the tracking tag ID.
      "CrossDeviceAttributionModelId": "IdentityAlliance"
    },
    {
      "AdvertiserId": "adv890xyz",
      "ConversionPixelName": "Inferred Brand Impact",
      "ConversionType": "123abc", // This is the tracking tag ID.
      "CrossDeviceAttributionModelId": "IdentityAlliance"
    }
  ]  
}

Response

The following is an example of a POST /v3/myreports/reportschedule response with the newly created report schedule.

{
   "ReportScheduleId":654321,
   "ReportScheduleName":"PartnerID Adgroup Performance Report HD",
   "ReportTemplateId":168005,
   "ReportFileFormat":"TSV",
   "PartnerFilters":[
      "partner123abc"
   ],
   "ReportDateRange":"LastXDays",
   "TimeZone":"UTC",
   "ReportDateFormat":"International",
   "ReportNumericFormat":"US",
   "IncludeHeaders":true,
   "LookbackDays":1,
   "ReportFrequency":"Daily",
   "ConversionPixelNames":[
      {
         "AdvertiserId":"adv890xyz",
         "ConversionPixelName":"Generic Inc Friends Conversion",
         "ConversionType":"abc123",
         "CrossDeviceAttributionModelId":"IdentityAlliance"
      },
      {
         "AdvertiserId":"adv890xyz",
         "ConversionPixelName":"Landing Page Visit",
         "ConversionType":"234def",
         "CrossDeviceAttributionModelId":"IdentityAlliance"
      },
      {
         "AdvertiserId":"adv890xyz",
         "ConversionPixelName":"Inferred Brand Impact",
         "ConversionType":"123abc",
         "CrossDeviceAttributionModelId":"IdentityAlliance"
      }
   ]
}

Best practices for custom report start and end dates

When setting a custom date range for your report, ensure that the start and end dates that you specify cover the date range you want.

Do not enter the same date in the StartDateInclusive and EndDateExclusive fields, or you'll get no data for your report.
Setting the EndDateExclusive value to today is only meaningful when today is different from the date you specified in the StartDateInclusive field.
To get a full month's report on the first of the next month, set the report start and end dates as follows:
- Set the StartDateInclusive value to the first day of the previous month or at least 30 days before the EndDateExclusive date.
- Set the EndDateExclusive value to the first day of the next month or one day after the last date you want to be included in your report, as the EndDateExclusive field counts up to the last date in the range and excludes that date.

The following table provides examples of different date ranges.

Start Date Inclusive	End DAte Exclusinve	Date Range	Report Duration
May 1	June 1	May 1 - May 31	Full month report.
May 1	May 31	May 1 - May 30	Nearly a full month report but the last day is excluded since `EndDateExclusive` drops the last date in the range.
May 1	May 1	No data	Zero days. To get a one-day report for May 1, the date range should be May 1 - May 2. See also Best practices.

Retrieve all report schedule facets

To retrieve all report schedule facets, such as data ranges, file formats, and status, use the GET /v3/myreports/reportschedule/facets endpoint.

Query report schedules

To retrieve report schedules for specified query filters, use the POST /v3/myreports/reportschedule/query endpoint.

Request

The following is a JSON example of a POST /v3/myreports/reportschedule/query request with a {token} placeholder for your API token and several filters, inclulding ReportScheduleIds, NameContains, and ShowOnlyRequestedByMe.

curl -H "Content-Type: application/json" -H "TTD-Auth:{token}" -X POST "https://api.thetradedesk.com/v3/myreports/reporttemplateheader/query" -d '{"ReportScheduleIds": [ "123456", "234567"], "NameContains": "HD", "ShowOnlyRequestedByMe": true, "PageStartIndex": 0, "PageSize": 10}'

Response

The following is an example of a POST /v3/myreports/reportschedule/query response with the report schedules that match the query filters specified in the request.

{
   "Result":[
      {
         "ReportScheduleId":123456,
         "ReportScheduleName":"Partner ABC Ad Group Performance Report HD",
         "RequestedByUserName":"urszula.etheridge",
         "CreationDateUtc":"2021-07-13T15:23:29.713",
         "ReportTemplateId":111111,
         "IsCompleted":false,
         "ReportScheduleStatus":"Disabled",
         "ReportFileFormat":"TSV",
         "PartnerFilters":[
            "partner123abc"
         ],
         "ReportDateRange":"Yesterday",
         "TimeZone":"UTC",
         "ReportDateFormat":"International",
         "ReportNumericFormat":"International",
         "IncludeHeaders":true,
         "ReportFrequency":"Daily",
         "ScheduleStartDate":"2021-07-13T00:00:00",
         "EmailAddresses":[]
      },
      {
         "ReportScheduleId":234567,
         "ReportScheduleName":"Partner XYZ Ad Group Performance Report HD",
         "RequestedByUserName":"urszula.etheridge",
         "CreationDateUtc":"2021-07-16T09:19:25.327",
         "ReportTemplateId":222222,
         "IsCompleted":true,
         "ReportScheduleStatus":"Active",
         "ReportFileFormat":"TSV",
         "PartnerFilters":[
            "partner098xyz"
         ],
         "ReportDateRange":"Yesterday",
         "TimeZone":"UTC",
         "ReportDateFormat":"International",
         "ReportNumericFormat":"US",
         "IncludeHeaders":true,
         "ReportFrequency":"Daily",
         "ScheduleStartDate":"2021-07-16T00:00:00",
         "EmailAddresses":[]
      }
   ],
   "ResultCount":2
}

Retrieve a report schedule for a given ID

To retrieve a specific report schedule by its ID, use the GET /v3/myreports/reportschedule/{scheduleid} endpoint.

Request

The following is an example of a GET /v3/myreports/reportschedule/{scheduleid} request with a {token} placeholder for your API token.

curl -H "Content-Type: application/json" -H "TTD-Auth:{token}" -X GET "https://api.thetradedesk.com/v3/myreports/reportschedule/123456"

Response

The following is an example of a GET /v3/myreports/reportschedule/{scheduleid} response with the report schedule that matches the ID specified in the request path parameter.

{
    "ReportScheduleId": 123456,
    "ReportScheduleName": "Partner ABC Ad Group Performance Report HD",
    "RequestedByUserName": "urszula.etheridge",
    "CreationDateUtc": "2021-07-16T09:19:25.327",
    "ReportTemplateId": 111111,
    "IsCompleted": false,
    "ReportScheduleStatus": "Disabled",
    "ReportFileFormat": "TSV",
    "PartnerFilters": [
        "partner123abc"
    ],
    "ReportDateRange": "Yesterday",
    "TimeZone": "UTC",
    "ReportDateFormat": "International",
    "ReportNumericFormat": "US",
    "IncludeHeaders": true,
    "ReportFrequency": "Daily",
    "ScheduleStartDate": "2021-07-16T00:00:00",
    "EmailAddresses": [],
}

Delete a report schedule for a given ID

To delete a specific report schedule by its ID, for example, to maintain the report schedule quota (currently 100 schedules) assigned to your account, use the DELETE /v3/myreports/reportschedule/{scheduleid} endpoint.

If you don't know the ID of the report schedule you want to delete, use the POST /v3/myreports/reportschedule/query endpoint to retrieve the report information.

Request

The following is an example of a DELETE /v3/myreports/reportschedule/{scheduleid} request with a {token} placeholder for your API token.

curl -H "Content-Type: application/json" -H "TTD-Auth:{token}" -X DELETE "https://api.thetradedesk.com/v3/myreports/reportschedule/123456"

FAQs

The following is a list of commonly asked questions about report schedules.

Do single report schedules count toward the 100 schedule limit?

Yes. This limit includes both recurring and single report schedules that have ReportFrequency set to Once. For example, if you schedule 100 single reports, you would need to wait for a report to run and finish before you can schedule another report.

Why was my report schedule automatically disabled?

The Trade Desk automatically disables a recurring report schedule in either of the following cases:

The schedule hasn't produced any report data for more than two months.
The reports generated by this schedule haven't been downloaded for more than 30 days.

In both cases, you receive a warning email two weeks before the schedule is disabled. To check whether a schedule was automatically disabled by the system, use the POST /v3/myreports/reportschedule/query endpoint and check the ReportScheduleStatus field.

To reactivate a disabled schedule, you must create a new one. For details, see Create a new report schedule with the same settings.

Are all report schedules subject to automatic disabling?

No. Here are the schedule types that do not get automatically disabled:

Schedules delivered directly to your own S3 bucket.
Schedules with exposure feeds, which use a separate expiration process.