Export API Overview

The Export API provides a way to retrieve large volumes of data from Pardot. It uses Pardot's existing API structures, patterns, and terminology.

When to Use the Export API

Use the Export API to retrieve large sets of data when you don't need synchronous completion responses or when query limitations are too restrictive. Currently, only visitor activity is supported.

How the Export API Works

An export is associated with a query and a data set in Pardot. When you create an export, the query is split into smaller queries, which return smaller sets of data. These smaller queries are processed in parallel, and the retrieved data is saved in CSV files. When the export is complete, the CSV files are available to download.

The order of the records returned in the CSV files is not guaranteed. The number of records in each CSV file varies, and all of the files associated with an export make up the full data set for the query.

The Export resource is used to create an export and get the status of an export. When the export is complete, the links to the CSV files containing the data are available in the resource.

Limitations

Expiration

The data associated with an export expires after 7 days. When data expires, the Export resource removes links to the CSV files and shows that the export has expired. Attempts to retrieve the data after an export expires fail.

CSV File Formatting

Procedures

A procedure is a query and execution plan used to retrieve the data. Each object has a different set of procedures.

Visitor Activity

filter_by_created_at

Retrieves all visitor activity records with a created_at value that is equal or greater than the created_after argument and less than or equal to the created_before argument.

Abilities

Action Requirements
Create export Prospects > Visitors > View ability
View export Prospects > Visitors > View ability and be the same user that created the export
View all exports Admin > Exports > View ability
Query exports Admin > Exports > View ability

To create an export with this procedure, the user must have the following:

To view an export with this procedure, the user must have the following:

OR

Arguments

NOTE: The range between created_after and created_before cannot exceed 1 year. When created_before is not specified, the current date is used to gauge the interval.

Using the Export API


Create

/api/export/version/4/do/create

Used to create an export of an object and procedure.

POST

Request Body

Content-Type must be application/json.

Input Representation

{
    "object": string,
    "procedure": {
        "name": string,
        "arguments": {
            "argument name": argument value,
            // additional arguments...
        }
    }
}

Success

Status Code: 200

Output Representation

{
    "export": {
        "id": int,
        "state": string,
        "isExpired": boolean,
        "resultRefs": string OR string[],
        "createdAt": datetime,
        "updatedAt": datetime
    }
}

Errors

Example

This is a request to execute the visitor activity procedure named filter_by_created_at, which retrieves all visitor activity data where the created_at value is between two dates. In this example, the data will be retrieved from December 25, 2019 to December 25, 2020.

POST /api/export/version/4/do/create
HOST: pi.pardot.com
Content-Type: application/json
Authorization: Pardot user_key=U,api_key=A
{
    "object": "visitorActivity",
    "procedure": {
        "name": "filter_by_created_at",
        "arguments": {
            "created_after": "2019-12-25 10:00:00",
            "created_before": "2020-12-25 24:59:59"
        }
    }
}

After sending the request as a POST, the response will be the following. From this response, the export has been queued for execution but has not started nor completed. We suggest waiting a few minutes before checking the Read endpoint for the new status.

{
    "id": 201917,
    "state": "Waiting",
    "isExpired": false
}

Read

/api/export/version/4/do/read/id/{id}

Used to retrieve the status of the export. Once an export is complete, the links to download the results are available in the result body.

GET

Params

{id}: The ID of the export.

Success

Status Code: 200

Output Representation

{
    "export": {
        "id": int,
        "state": string,
        "isExpired": boolean,
        "resultRefs": string OR string[],
        "createdAt": datetime,
        "updatedAt": datetime
    }
}

Errors

Example

After calling the Create endpoint, the ID of the export will be given in the response. This ID is used in the URL to call the Read endpoint.

GET /api/export/version/4/do/read/id/201917
HOST: pi.pardot.com
Content-Type: application/json
Authorization: Pardot user_key=U,api_key=A

If the export is waiting to be processed, state is "Waiting", like the following example.

{
    "id": 201917,
    "state": "Waiting",
    "isExpired": false
}

If the export is finished, state is "Complete" and resultRefs contains URLs to download the CSV files.

{
    "id": 201917,
    "state": "Complete",
    "isExpired": false,
    "resultRefs": [
        "https://www.pardot.com/api/export/version/4/do/downloadResults/id/201917/file/23191",
        "https://www.pardot.com/api/export/version/4/do/downloadResults/id/201917/file/20201",
        "https://www.pardot.com/api/export/version/4/do/downloadResults/id/201917/file/20102"
    ]
}

Query

/api/export/version/4/do/query

Used by administrators to retrieve a list of exports and their status. A user must have the “Admin > Exports > View” ability to execute this endpoint.

GET

Params

Success

Status Code: 200

Output Representation

Note that the export representation returned in query doesn’t contain resultRefs. Use the read endpoint for the export to get the full export representation.

{
    "result": {
        "total_results": int,
        "export": [
            {
                "id": int,
                "state": string,
                "isExpired": boolean,
                "resultRefs": string OR string[],
                "createdAt": datetime,
                "updatedAt": datetime
            }
        ]
    }
}

Errors


Download Results

The URLs retrieved from the Read endpoint can be used to download the results of the export. A failure occurs when attempting to download any results from an expired export. See Expiration for more information.

GET

Success

The data represented in CSV format. See the CSV Format section for more information.

Errors


Enums

Export State