Manage conversion lift studies

After you have completed your initial setup, you can retrieve and conduct conversion lift studies that advertisers create in the platform. During this process, you will retrieve studies, approve or reject them based on your feasibility requirements, conduct them, and submit the results to the advertiser.

Before you begin

Before you integrate your conversion lift study solution into the platform, here's what you need to know:

To use the Conversion Lift Study API, you must first complete the initial setup. This includes submitting all required implementation details, such as pixel templates or a designated method for receiving exposure files.
To access the Conversion Lift API, you must use platform authentication and the provider ID assigned during your initial setup.

What advertisers control

Here's what the advertiser controls in the platform UI:

The advertiser sets the study's start and end dates in the platform UI and may adjust them later. You can conduct the study and submit results on, before, or after the start date.
After the advertiser creates the study, they can add more campaigns to it.

What you can do

Here's what you can do as a conversion lift provider:

If a campaign has insufficient impression data, narrow targeting, or doesn't meet your feasibility requirements, you can reject the study.
You can submit the results file directly to the platform using a generated upload URL.
If needed, you can delete your results file or download it later. For details, see Results file management tasks.

TIP: If you are new to GraphQL, check out our GraphQL API Resource Hub and familiarize yourself with the basics.

Study statuses

Throughout the integration process, you will update the status of a study to reflect its current stage in the workflow. The following table lists the possible status values that you can set for a study.

Status	Description
`PENDING`	The study is ready for you to retrieve it.
`LIVE`	The study is being conducted.
`REJECTED`	The study does not meet your feasibility requirements. NOTE: Be sure to provide the reason in the `rejectedReason` field.
`APPROVED`	The study meets your feasibility requirements, and you have approved it and are ready to conduct it.
`COMPLETED`	You finished conducting the study and sent a report of the results to the advertiser in the platform.

Integration workflow diagram

The following diagram illustrates the process outlined in the next section, which also includes links to the respective step-by-step instructions and provides additional guidance on the decisions you might need to make along the way.

For a complete list of supported status values, see Study statuses.

Integration workflow

The following table outlines the step-by-step process, while the diagram in the preceding section illustrates the decision-making workflow.

Step		Task	Operation	Notes
1		Retrieve the studies with the `PENDING` status in one of the following ways:	See the rows below.	The Trade Desk recommends checking for new studies every hour or, at minimum, once per day.
	a	Retrieve a paginated list of studies.	`conversionLiftProvider` query	Use this option to browse or query multiple studies across your integration. For details on how to use paginated lists in GraphQL, see GQL API response pagination in our GraphQL Resource Hub.
	b	Retrieve a list of changed studies since the last change tracking version.	`conversionLiftStudyDelta` query	Use this option to sync only new or changed studies since your last fetch.
	c	Retrieve a single study by its ID.	`conversionLiftStudy` query	Use this option when you already know the study ID and want details about that specific study.
2		If the study meets your feasibility requirements, update the status to `APPROVED`.	`conversionLiftStudyUpdate` mutation	If the study does not meet your feasibility requirements, set the status to `REJECTED`.
3		When you are ready to conduct the study, update the status to `LIVE`.	`conversionLiftStudyUpdate` mutation	You can conduct the study before, after, or on the start date.
4		Collect exposure data from the pixel or exposure file method you provided during the initial setup process and conduct the study until the end date is reached.	N/A	To correlate the exposure data with the appropriate study, use the conversion IDs and campaign IDs listed in the study.
5		During the in-flight date range or after the study reaches its end date, upload the study results to the platform.	`fileUpload` mutation	The file can be in any common media format, such as CSV, PPT, or XLSX. Be sure to save the file ID for future reference—otherwise, you'll have to re-upload the file before proceeding.
6		Set the metadata for the results file.	`conversionLiftExperimentThirdPartyResultCreate` mutation	This requires the file ID returned in step 5.
7		Update the status to `COMPLETED`.	`conversionLiftStudyUpdate` mutation	None.

The following sections detail each step in the integration workflow process. For details about how to retrieve and delete a results file, see Results file management tasks.

Retrieve studies

When an advertiser creates a conversion lift study, the platform automatically sets its status to PENDING. You then retrieve studies, filter for those in the PENDING state, and either approve or reject them based on your feasibility requirements.

TIP: The Trade Desk recommends checking for new studies every hour or, at minimum, once per day. The platform updates its database of studies every 30 seconds.

To retrieve studies, use one of the following methods:

A paginated list of studies.
A list of changed studies since the last change tracking version.
A single study by its ID.

Retrieve a paginated list of studies

To retrieve multiple studies by status, use the conversionLiftProvider query, include your provider ID, and set the where.status field to PENDING or any other status.

query GetMultipleConversionLiftStudiesExample {
  conversionLiftProvider(conversionLiftProviderId: PROVIDER_ID_INTEGER_PLACEHOLDER) {
    conversionLiftStudies(where: { status: { eq: PENDING } }) {
      nodes {
        advertiserBasicInfo {
          id
          name
        }
        id
        emailAddresses
        endDate
        status
        name
      }
      edges {
        cursor
      }
      pageInfo {
        endCursor
        hasNextPage
        hasPreviousPage
        startCursor
      }
      totalCount
    }
  }
}

Retrieve all changed studies

To track changes made by advertisers in the platform, you can retrieve a list of study data objects in the order they were last updated using their change tracking version. To do this, use the conversionLiftStudyDelta query and include the following input fields:

The conversionLiftProvider.ids field with your provider ID.
The changeTrackingVersion field with the tracking version to start from. To retrieve all studies and their tracking versions, set this value to 0.

TIP: To return the tracking version of the next updated study, include the nextChangeTrackingVersion field. You can then include this value in the changeTrackingVersion field in subsequent requests.

Here's an example conversionLiftStudyDelta query that retrieves all studies updated after a specified changeTrackingVersion, starting from version 0.

query GetConversionLiftStudyDeltaExample {
  conversionLiftStudyDelta(
    input: {
      conversionLiftProvider: {
        changeTrackingVersion: 0
        ids: [PROVIDER_ID_PLACEHOLDER]
      }
    }
  ) {
    conversionLiftStudyData {
      id
    }
    currentMinimumTrackingVersion
    moreAvailable
    nextChangeTrackingVersion
  }
}

Retrieve a single study

To retrieve a specific study by its ID, use the conversionLiftStudy query and include your provider ID and the study ID.

TIP: To retrieve your provider-specific fields, include the ConversionLiftStudy{PROVIDER_NAME}Attributes field where {PROVIDER_NAME} is your company name.

query GetSingleStudyExample {
  conversionLiftStudy(providerId: "PROVIDER_ID_PLACEHOLDER", studyId: "LIFT_STUDY_ID_PLACEHOLDER") {
    id
    studyId
    createdAt
    lastUpdatedAt
    name
    startDate
    endDate
    status
    rejectionReason
    emailAddresses
    advertiserBasicInfo {
      id
    }
    provider {
      id
    }
    providerAttributes {
      __typename
      ... on ConversionLiftStudy{PROVIDER_NAME}Attributes {
        id
        campaignBasicInfos {
          id
          name
        }
        itemsets(first: 10) {
          nodes {
            id
          }
        }
      }
    }
  }
}

Update the study status

After you retrieve a pending study and are ready to approve, reject, or conduct it, you must update its status. To update a study's status at each stage of the workflow, use the conversionLiftStudyUpdate mutation. In the updateByProvider field, include the study ID and the new status.

NOTE: When you are ready to conduct the study, use this mutation again and set the status to LIVE.

Here's an example conversionLiftStudyUpdate mutation for approving a study.

mutation {
  conversionLiftStudyUpdate(
    input: {
      updateByProvider: {
        studyId: "STUDY_ID_PLACEHOLDER"
        status: APPROVED
      }
    }
  ) {
    data {
      id
      status
    }
    errors {
      __typename
      ... on MutationError {
        field
        message
      }
    }
  }
}

Here's an example conversionLiftStudyUpdate mutation for rejecting a study and providing a reason for the rejection.

mutation {
  conversionLiftStudyUpdate(
    input: {
      updateByProvider: {
        studyId: "STUDY_ID_PLACEHOLDER"
        status: REJECTED
        rejectedReason: "Expected impressions are too low."
      }
    }
  ) {
    data {
      id
      status
    }
    errors {
      __typename
      ... on MutationError {
        field
        message
      }
    }
  }
}

Upload study results to the platform

To upload a file of the study results, complete the following steps.

Step	Task	Notes
1	Generate the upload URL.	You must include the period in the file extension. Otherwise, the upload to the generated URL will fail. Save the returned file ID for future reference. If you lose it, you’ll need to re-upload the file before proceeding. The generated upload URL is a presigned S3 URL, which expires after 30 minutes.
2	Use the URL to upload the file.	Supported file types include CSV, PPT, XLSX, and other common formats. You have the option of writing your own code to upload the file or using any preferred method, such as a Python script or a cURL command. If you choose to write your own code, make sure it correctly handles the request and response formats required for presigned S3 upload URLs.

To generate an upload URL, use the fileUpload mutation and specify your file extension, including the period, in the contentType field.

IMPORTANT: You must include the period in the file extension. Otherwise, the upload to the generated URL will fail.

mutation {
  fileUpload(contentType: ".csv") {
    id
    uploadUrl
  }
}

A successful response returns a presigned Amazon S3 URL. After you upload your study results file, you must set the metadata for the file. This metadata surfaces your results to the advertiser in the platform.

Set metadata for the results file

After uploading the file, you must set its metadata to surface the results to the advertiser. To do this, use the conversionLiftExperimentThirdPartyResultCreate mutation and include the required fields, which include the name of the file, its extension, and the file ID you uploaded.

Here's an example of a conversionLiftExperimentThirdPartyResultCreate mutation for setting metadata for a conversion lift results file.

mutation {
  conversionLiftExperimentThirdPartyResultCreate(
    input: {
      input: {
        conversionLiftExperimentId: STUDY_ID_PLACEHOLDER
        conversionLiftProviderId: PROVIDER_ID_INTEGER_PLACEHOLDER
        fileId: "f7d3c2b9-8b72-4d4b-bb6a-12e3f9c76de4"
        fileNameIncludingFileExtension: "FILE_NAME_PLACEHOLDER.csv"
        resultDate: "2025-06-23"
      }
    }
  ) {
    data {
      data {
        createdAt
        downloadUrl
        fileName
        id
        resultDate
      }
      userErrors {
        field
        message
      }
    }
  }
}

After you set the metadata for the results file, you can set the status of the study to COMPLETED. If needed, you can also retrieve and delete your results file. For details, see Results file management tasks.

Results file management tasks

After uploading your results file, you may download it for reference or delete it, if needed. The following table lists the tasks for downloading and deleting a results file.

IMPORTANT: You must set the metadata for the results file before you can perform any of these tasks.

Task	Operation
Retrieve the results file of a study.	`conversionLiftStudy` query
Delete a results file.	`conversionLiftExperimentThirdPartyResultDelete` mutation

Retrieve results files

To retrieve all the study results files, use the conversionLiftStudy query and include your provider ID and the study ID.

NOTE: You can retrieve a results file only if you set the metadata for it.

query GetConversionLiftStudyExample {
  conversionLiftStudy(providerId: "PROVIDER_ID_PLACEHOLDER", studyId: "STUDY_ID_PLACEHOLDER") {
    name
    id
    results {
      nodes {
        createdAt
        downloadUrl
        fileName
        id
        resultDate
      }
    }
  }
}

You can download the results file from the URL in the downloadUrl field.

NOTE: The results.nodes.id value is the platform file ID that was generated after you set the metadata for the file.

Delete a results file

After you upload and set the metadata for a results file, you can delete it from the platform if, for example, you uploaded the wrong file. Here's what you need to know:

You cannot recover a file after you delete it.
You can delete a results file only if you've already set the metadata for it.
To delete a file, you must have the results file ID that was generated after you set the metadata for the file. See also Retrieve results files.

To delete a results file, use the conversionLiftExperimentThirdPartyResultDelete mutation and, in the conversionLiftThirdPartyResultId field, include the results file ID that was generated after you set the metadata for the file.

mutation {
  conversionLiftExperimentThirdPartyResultDelete(
    input: {
      conversionLiftThirdPartyResultId: 15
    }
  ) {
    data {
      data {
        wasSuccessfullyDeleted
      }
      userErrors {
        field
        message
      }
    }
  }
}

FAQs

The following is a list of frequently asked questions about integrating conversion lift studies.

Can the advertiser cancel the study before the end date?

No. After an advertiser creates the study, they can modify the end date, but they cannot cancel the study.

Can I send the study results before the end date?

Yes. You can send the study results before the study end date.

Can the advertiser still access and modify the study after I reject it?

Yes. After you reject a study, the study is not deleted or archived. The advertiser can still access the study in the platform UI and modify the information so that it meets your feasibility requirements. After the advertiser modifies the study to meet your feasibility requirements and submits it, use the same workflow process to retrieve it.

What type of file can I upload when I submit the results?

You can upload any common media file type such as CSV, PPT, or XLSX.

Can I upload multiple files for the study?

You can upload multiple files per study, but you cannot upload multiple files at the same time. For example, to send both a PPT and a CSV file, you must upload each file individually.

If I no longer have the results file ID after I upload my file, how can I retrieve it?

If you no longer have the file ID after uploading the file and have not set the metadata for it, you must re-upload your results file. You cannot retrieve your results file if you do not have the file ID. The file will be deleted from the system after 31 days.

How do I approve or reject a study?

To approve or reject a study, update its status to either APPROVED or REJECTED.

How long is the upload URL valid?

The upload URL is valid for 30 minutes.

How do I share study results with the advertiser?

To send the study results to the advertiser in the platform, you must upload the results file and set its metadata.

Can I use REST to integrate my services with the platform?

No. You can use only GraphQL. For details, see Integration workflow.