Predefined reports

The Trade Desk platform offers reports with predefined metrics and lookback periods. You generate these reports from templates to measure campaign performance and provide other insights without time-consuming customization. Here's what you need to know about predefined reports:

• Predefined reports are available and tailored to the advertiser, campaign, and ad group level.
• You cannot customize the metrics or lookback periods in predefined reports.
• The date range in each report is based on its lookback period.
• Reports are delivered in CSV format.
• You can generate reports at any time and use a download link to retrieve them.
• Depending on the amount of data, generating reports can take up to a few minutes before they become available for download.
• You can retrieve the processing status and download links of multiple predefined reports at the same time.

NOTE: Access to predefined reports is currently limited to a curated selection of templates, which may vary based on the advertiser, their use cases, and permission levels. This set of predefined reports is referred to as "suggested templates," which have a userGenerated value of false in the GraphQL API.

Frequently suggested predefined report templates

The following table lists some of the commonly used predefined reports offered as suggested templates.

TIP: Different reports answer different business questions. For example, Reach and Frequency can help answer the following question: How many households has my advertiser reached over the last 30 days? To view a list of business questions for each template, include the keyBusinessQuestions field when you retrieve a template.

Report tasks

The following table lists the tasks associated with downloading reports.

Retrieve suggested predefined report templates

You can retrieve all the templates you have access to, or filter them by type, name, and so on. To retrieve a list of all predefined templates, use the GraphQL reportingTemplates query and set the userGenerated filter to false.

TIP: To view the report columns, names, usage, and so on, include the templateStructure object.

The following reportingTemplates query example retrieves a list of predefined optimization templates. For each predefined report, the query returns information such as the template ID, name, and type.

query GetTemplateDetailsExample {
  reportingTemplates(
    where: {
      userGenerated: { eq: false }
      recommendedTemplateType: { eq: OPTIMIZATION }
    }
  ) {
    nodes {
      id
      name
      userGenerated
      templateStructure {
        tabName
        fields {
          columnName
          columnOrder
          columnUsageType
        }
        metrics {
          columnName
          columnOrder
          columnUsageType
        }
      }
      recommendedTemplateDetails {
        templateType
        channels
        deviceTypes
        frequencyType
        lookBackWindowInDays
        roiGoalTypes
        keyBusinessQuestions {
          id
          value
        }
        description {
          id
          value
        }
      }
    }
  }
}

After you identify the templates you want to use, take note of their IDs and generate the reports.

Generate a report

After you retrieve and identify the predefined reports you want to use and are ready to generate the report, use the GraphQL reportScheduleCreateFromSuggestedTemplate mutation and include the following:

The template ID.
The ID of the advertiser, campaign, or ad group for which you want to run a report.
A custom name for the report.

NOTE: You can use this mutation to generate only one report at a time.

mutation {
  reportScheduleCreateFromSuggestedTemplate(
    input: {
      entity: { advertiserId: "ADVERTISER_ID_PLACEHOLDER" }
      reportName: "Advertiser Performance Insights Report"
      reportTemplateId: "TEMPLATE_ID_PLACEHOLDER"
    }
  ) {
    data {
      reportScheduleSourceReferenceId
    }
    userErrors {
      field
      message
    }
  }
}

Depending on the amount of data the system needs to process, the report usually becomes available to download after a few minutes. After you begin generating the report, you can check its status by using the template ID.

Check the report status and download the report

After you generate your reports, you can check their statuses and retrieve their download links.

IMPORTANT: The download link returned for these reports is an API download link that requires an API token to use.

To retrieve a list of report processing and schedule statuses, use the GraphQL myReportsReportSchedules query. Here's what you need to know:

• You can retrieve the status and the download link in the same query.
• There are multiple filters available such as name, last status change date, lookback window type, and so on.
• After the report is in the COMPLETED state, you can retrieve the download link to download the report.
• To check the status of a specific report, in the executions.some.id argument, include the report schedule ID.

Here's an example of how to retrieve reports based on the last status change date.

query GetReportStatuses {
  myReportsReportSchedules(
    where: {
      executions: { some: { lastStatusChangeDate: { gte: "2025-07-01" } } }
    }
  ) {
    nodes {
      id
      name
      status
      filters {
        advertiserFilters {
          name
        }
        partnerFilters {
          name
        }
      }
      timezone
      executions {
        nodes {
          id
          reportStartDateInclusive
          reportEndDateExclusive
          lastStatusChangeDate
          state
          delivery {
            downloadLink
            deliveredDate
          }
        }
      }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}

Report statuses

The following table lists the possible state values or statuses for generating reports.

FAQs

The following is a list of commonly asked questions about predefined reports.

Can I customize predefined reports?

No. You can't modify predefined reports using the API, but you can create your own customized reports in the Platform UI and use the REST API to schedule them. For details, see User-defined reports.

How long does it take to generate a report?

Most reports are available to download within a few minutes, but the time depends on the amount of data being processed.

What type of metrics are in each report?

Each report includes a specific set of metrics based on its reporting level (advertiser, campaign, or ad group). To retrieve the metrics or columns in a report, use the reportingTemplates query and include the templateStructure field. For details, see Retrieve suggested predefined report templates.

Can I create a recurring schedule for a predefined report?

No. You must manually generate the report each time. In future updates, you'll be able to schedule reports to run on a recurring cadence—stay tuned for more enhancements!