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
- The Export API is subject to the daily Pardot API call limit and the concurrent Pardot API call limit for your account.
- Export API calls are executed sequentially for each account, with older exports being processed before newer exports.
- The number of fields specified in the Export API calls can't exceed 150.
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
- The first row contains the name of the field.
- The second row and beyond contain the record data.
- Dates are returned in the user’s timezone at the time they created the export.
- For example, if a user is in “PST” timezone and creates an export, the dates in the export are in “PST”. If a second user is in “EST” timezone and downloads the exported files, the dates in the export are in “PST”.
- If a user’s timezone changes, previous exports created by the user have dates formatted in the previous timezone. Dates in new exports use the new timezone.
- Dates are returned in the standard Pardot API date format of
YYYY-MM-DD HH:mm:SS
. - Fields with null values are represented as an empty value in CSV.
Procedures
A procedure is a query and execution plan used to retrieve the data. Each object has a different set of procedures.
Visitor Activity
Fields
Select the visitor activity fields you want to export. Following are the fields that are available for visitor activity. The value for fields
must be an array of strings of the available fields.
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:
- “Prospects > Visitors > View“ ability
To view an export with this procedure, the user must have the following:
- “Prospects > Visitors > View“ ability AND
- The user must be the same as the user that created the export
OR
- “Admin > Exports > View”
filter_by_created_at
Retrieves all visitor activity records with a created_at
value that is greater than the created_after
argument and less than the created_before
argument.
Arguments
- created_after: Selects visitor activities that were created after the specified time. The value can be
today
,yesterday
,last_7_days
,this_month
,last_month
, or a custom time specified in GNU Date Input Syntax format. - created_before: (Optional) Selects visitor activities that were created before the specified time. This value must be after the value in
created_after
. If this argument is not specified, then no upper boundary is used in the query, and all data after thecreated_after
is returned. The value can betoday
,yesterday
,last_7_days
,this_month
,last_month
, or a custom time specified in GNU Date Input Syntax format. - type: (Optional) Selects visitor activities of the specified types. If this argument is not specified, then all of the visitor activities belonging to any type is returned. See a list of available Visitor Activity Types in Visitor Activity in Object Field References.
- prospect_only: (Optional) Selects only those visitor activities associated with a prospect. When this field is set to
false
, all visitor activities are returned. The values can betrue
orfalse
.
filter_by_updated_at
Retrieves all visitor activity records with an updated_at
value that is greater than the updated_after
argument and less than the updated_before
argument.
Arguments
- updated_after: Selects visitor activities that were updated after the specified time. The value can be
today
,yesterday
,last_7_days
,this_month
,last_month
, or a custom time specified in GNU Date Input Syntax format. - updated_before: (Optional) Selects visitor activities that were updated before the specified time. This value must be after the value in
updated_after
. If this argument is not specified, then no upper boundary is used in the query, and all data after theupdated_after
is returned. The value can betoday
,yesterday
,last_7_days
,this_month
,last_month
, or a custom time specified in GNU Date Input Syntax format. - type: (Optional) Selects visitor activities of the specified types. If this argument is not specified, then all visitor activities belonging to any type are returned. See a list of available Visitor Activity Types in Visitor Activity in Object Field References.
- prospect_only: (Optional) Selects only those visitor activities associated with a prospect. When this field is set to
false
, all visitor activities are returned. The values can betrue
orfalse
.
NOTE: The range between updated_after and updated_before cannot exceed 1 year. When updated_before is not specified, the current date is used to gauge the interval.
List Membership
Fields
Select the list membership fields that you want to export. Following are the fields that are available for list membership. The value for fields
must be an array of strings of the available fields.
Abilities
Action | Requirements |
---|---|
Create export | Marketing > Segmentation > Lists > View ability and Prospects > Visitors > View ability |
View export | Marketing > Segmentation > Lists > View ability and Prospects > Visitors > View ability and 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:
- “Marketing > Segmentation > Lists > View“ ability AND
- “Prospects > Visitors > View“ ability
To view an export with this procedure, the user must have the following:
- “Marketing > Segmentation > Lists > View“ ability AND
- “Prospects > Visitors > View“ ability AND
- The user must be the same as the user that created the export
OR
- “Admin > Exports > View”
filter_by_created_at
Retrieves all list membership records with a created_at
value that is greater than the created_after
argument and less than the created_before
argument.
Arguments
- created_after: Selects list membership that were created after the specified time. The value can be
today
,yesterday
,last_7_days
,this_month
,last_month
, or a custom time specified in GNU Date Input Syntax format. - created_before: (Optional) Selects list memberships that were created before the specified time. This value must be after the value in
created_after
. If this argument is not specified, then no upper boundary is used in the query, and all data after thecreated_after
is returned. The value can betoday
,yesterday
,last_7_days
,this_month
,last_month
, or a custom time specified in GNU Date Input Syntax format. - deleted: (Optional) Selects list membership based on if it is deleted or not. The value can be
true
,false
, orall
.
filter_by_updated_at
Retrieves all list membership records with a updated_at
value that is greater than the updated_after
argument and less than the updated_before
argument.
Arguments
- updated_after: Selects list membership that were created after the specified time. The value can be
today
,yesterday
,last_7_days
,this_month
,last_month
, or a custom time specified in GNU Date Input Syntax format. - updated_before: (Optional) Selects list membership that were created before the specified time. This value must be after the value in
updated_after
. If this argument is not specified, then no upper boundary is used in the query, and all data after theupdated_after
is returned. The value can betoday
,yesterday
,last_7_days
,this_month
,last_month
, or a custom time specified in GNU Date Input Syntax format. - deleted: (Optional) Selects list membership based on if it is deleted or not. The value can be
true
,false
, orall
.
NOTE: The range between created_after and created_before or updated_after and updated_before cannot exceed 1 year. When created_before is not specified, the current date is used to gauge the interval.
Prospect
Fields
Select the prospect fields that you want to export. Following and additional exportable fields are the standard fields that are available for prospect. The value for fields
must be an array of strings of the available fields.
In addition to the standard fields, custom fields can also be exported. To include the most recent value in custom fields, provide the <field_id> in the field array. Multi-select field values export separated by semi-colons.
filter_by_updated_at
Retrieves all prospect records with a updated_at
value that is greater than the updated_after
argument and less than the updated_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:
- “Prospects > Visitors > View“ ability
To view an export with this procedure, the user must have the following:
- “Prospects > Visitors > View“ ability AND
- The user must be the same as the user that created the export
OR
- “Admin > Exports > View”
Arguments
- updated_after: Selects prospects that were updated after the specified time. The value can be
today
,yesterday
,last_7_days
,this_month
,last_month
, or a custom time specified in GNU Date Input Syntax format. - updated_before: (Optional) Selects prospects that were created before the specified time. This value must be after the value in
updated_after
. If this argument is not specified, then no upper boundary is used in the query, and all data after theupdated_after
is returned. The value can betoday
,yesterday
,last_7_days
,this_month
,last_month
, or a custom time specified in GNU Date Input Syntax format. - deleted: Includes deleted prospects. This argument must be set to
all
. Both deleted and not deleted prospects are returned.
NOTE: The range between updated_after and updated_before cannot exceed 1 year. When updated_before is not specified, the current date is used to gauge the interval.
Prospect Account
Fields
Select the prospect account fields you want to export. Following are the fields that are available for prospect account. The value for fields
must be an array of strings of the available fields.
Abilities
Action | Requirements |
---|---|
Create export | Prospects > Prospect Accounts > View ability |
View export | Prospects > Prospect Accounts > 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:
- “Prospects > Prospect Accounts > View“ ability
To view an export with this procedure, the user must have the following:
- “Prospects > Prospect Accounts > View“ ability AND
- The user must be the same as the user that created the export
OR
- “Admin > Exports > View”
filter_by_prospect_updated_at
Retrieves all prospect account records associated with a prospect that has a updated_at
value that is greater than the prospect_updated_after
argument and less than the prospect_updated_before
argument.
Arguments
- prospect_updated_after: Selects prospect accounts associated with a prospect that has been updated after the specified time. The value can be
today
,yesterday
,last_7_days
,this_month
,last_month
, or a custom time specified in GNU Date Input Syntax format. - prospect_updated_before: (Optional) Selects prospect accounts associated with a prospect that has been updated before the specified time. This value must be after the value in
prospect_updated_after
. If this argument is not specified, then no upper boundary is used in the query, and all data after theprospect_updated_after
is returned. The value can betoday
,yesterday
,last_7_days
,this_month
,last_month
, or a custom time specified in GNU Date Input Syntax format. - prospect_deleted: (Optional) Selects prospect account based on whether it is associated with a prospect that has been deleted. The value can be
true
,false
, orall
. Default value isfalse
.
NOTE: The range between prospect_updated_after and prospect_updated_before cannot exceed 1 year. When prospect_updated_before is not specified, the current date is used to gauge the interval.
filter_by_updated_at
Retrieves all prospect account records with an updated_at
value that is greater than the updated_after
argument and less than the updated_before
argument.
Arguments
- updated_after: Selects prospect accounts that have been updated after the specified time. The value can be
today
,yesterday
,last_7_days
,this_month
,last_month
, or a custom time specified in GNU Date Input Syntax format. - updated_before: (Optional) Selects prospect accounts that have been updated before the specified time. This value must be after the value in
updated_after
. If this argument is not specified, then no upper boundary is used in the query, and all data after theupdated_after
is returned. The value can betoday
,yesterday
,last_7_days
,this_month
,last_month
, or a custom time specified in GNU Date Input Syntax format. - deleted: (Optional) Selects prospect accounts based on whether they have been deleted. The value can be
true
,false
, orall
. Default value isfalse
.
NOTE: The range between updated_after and updated_before cannot exceed 1 year. When updated_before is not specified, the current date is used to gauge the interval.
Visitor
Fields
Select the visitor fields you want to export. Following are the fields that are available for visitor. The value for fields
must be an array of strings of the available fields.
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:
- “Prospects > Visitors > View“ ability
To view an export with this procedure, the user must have the following:
- “Prospects > Visitors > View“ ability AND
- The user must be the same as the user that created the export
OR
- “Admin > Exports > View”
filter_by_prospect_updated_at
Retrieves all visitor records associated with a prospect that has an updated_at
value that is greater than the prospect_updated_after
argument and less than the prospect_updated_before
argument.
Arguments
- prospect_updated_after: Selects visitors associated with a prospect that has been updated after the specified time. The value can be
today
,yesterday
,last_7_days
,this_month
,last_month
, or a custom time specified in GNU Date Input Syntax format. - prospect_updated_before: (Optional) Selects visitors associated with a prospect that has been updated before the specified time. This value must be after the value in
prospect_updated_after
. If this argument is not specified, then no upper boundary is used in the query, and all data after theprospect_updated_after
is returned. The value can betoday
,yesterday
,last_7_days
,this_month
,last_month
, or a custom time specified in GNU Date Input Syntax format. - prospect_deleted: (Optional) Selects visitor based on whether it is associated with a prospect that has been deleted. The value can be
true
,false
, orall
. Default value isfalse
. - filter_type: More than one visitor can be associated with a single prospect. This argument controls which visitor will be returned per prospect. The value can be
first
orlast
.
NOTE: The range between prospect_updated_after and prospect_updated_before cannot exceed 1 year. When prospect_updated_before is not specified, the current date is used to gauge the interval.
filter_by_updated_at
Retrieves all visitor records with an updated_at
value that is greater than the updated_after
argument and less than the updated_before
argument.
Arguments
- updated_after: Selects visitors that have been updated after the specified time. The value can be
today
,yesterday
,last_7_days
,this_month
,last_month
, or a custom time specified in GNU Date Input Syntax format. - updated_before: (Optional) Selects visitors that have been updated before the specified time. This value must be after the value in
updated_after
. If this argument is not specified, then no upper boundary is used in the query, and all data after theupdated_after
is returned. The value can betoday
,yesterday
,last_7_days
,this_month
,last_month
, or a custom time specified in GNU Date Input Syntax format. - deleted: (Optional) Selects visitors based on whether they have been deleted. The value can be
true
,false
, orall
. Default value isfalse
.
NOTE: The range between updated_after and updated_before cannot exceed 1 year. When updated_before is not specified, the current date is used to gauge the interval.
Using the Export API
Create
/api/export/version/3/do/create
Used to create an export of an object and procedure.
POST
Request Body
Content-Type must be application/json
.
Input Representation
- object: Specifies which object to export. Currently only "visitorActivity" is supported.
- fields: Specifies the fields that will be exported. If no
fields
value is given, all available fields will be exported. - procedure: The procedure to execute. A procedure is a query and execution plan used to retrieve data. Each object has a different set of procedures. See the Procedures section for available procedures.
- name: The name of the procedure.
- arguments: Arguments used to manipulate the behavior of the procedure. These arguments are specific to the procedure. See the documentation for the procedure to see which arguments apply. If duplicate argument names are provided the latter value will be used.
{
"object": string,
"fields": [string, string, ....],
"procedure": {
"name": string,
"arguments": {
"argument name": argument value,
// additional arguments...
}
}
}
Success
Status Code: 200
Output Representation
- id: The ID of the export. ID is used to check the status of the export.
- state: The state of the export. Displays "Waiting" when the export has been queued for processing, "Processing" when the server is working on the export and "Complete" when the export has completed. See Export State enum.
- isExpired: Indicates that the export has expired. When an export has expired, this will return
true
and no data associated to the export can be downloaded. - resultRefs: (Optional) This property appears when an export is complete, and it contains a list of URLS to CSV files available for download. If there is no data associated with the export, this property is absent. If there is only a single CSV file available for download, this property is a string containing the URL to download the file. If there are multiple CSV files, resultRefs is an array of URLs.
- createdAt: The date and time the export was created in the timezone of the user making the request.
- updatedAt: The date and time the export was updated in the timezone of the user making the request.
{
"export": {
"id": int,
"state": string,
"isExpired": boolean,
"resultRefs": string OR string[],
"createdAt": datetime,
"updatedAt": datetime
}
}
Errors
- Status Code: 4xx
- Error codes: See Error Codes & Messages
Example
Here 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 is retrieved from December 25, 2019 to December 25, 2020.
POST /api/export/version/3/do/create
HOST: pi.pardot.com
Content-Type: application/json
Authorization: Pardot user_key=U,api_key=A
{
"object": "visitorActivity",
"fields": ["id", "prospect_id", "visitor_id", "type_name", "created_at"],
"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 is as follows. From this response we know the export is queued for execution but hasn't started or 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/3/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
- id: The ID of the export. This ID is used to check the status of the export.
- state: The state of the export. Displays "Waiting" when the export has been queued for processing, "Processing" when the server is working on the export and "Complete" when the export is completed. See Export State enum.
- isExpired: Indicates that the export has expired. After an export has expired, this will return true and no data associated with the export can be downloaded.
- resultRefs: (Optional) This property appears only when the export has completed and contains a list of URLS to CSV files available for download. If there is no data associated with the export, this property is absent. If there is only a single CSV file available for download, resultRefs is a string containing the URL to download the file. If there are multiple CSV files, resultRefs is an array of URLs. The order of the URLs in the array is not significant.
- createdAt: The date and time the export was created in the timezone of the user making the request.
- updatedAt: The date and time the export was updated in the timezone of the user making the request.
{
"export": {
"id": int,
"state": string,
"isExpired": boolean,
"resultRefs": string OR string[],
"createdAt": datetime,
"updatedAt": datetime
}
}
Errors
- Status Code: 4xx
- Error codes: See Error Codes & Messages
Example
After calling the Create endpoint, the ID of the export is given in the response. This ID is used in the URL to call the Read endpoint.
GET /api/export/version/3/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", as in 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/3/do/downloadResults/id/201917/file/23191",
"https://www.pardot.com/api/export/version/3/do/downloadResults/id/201917/file/20201",
"https://www.pardot.com/api/export/version/3/do/downloadResults/id/201917/file/20102"
]
}
Query
/api/export/version/3/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
- created_after: (Optional) Filters the results to return only exports that were created after the specified time.
- created_before: (Optional) Filters the results to return only exports that were created before the specified time.
- updated_after: (Optional) Filters the results to return only exports that were updated after the specified time.
- updated_before: (Optional) Filters the results to return only exports that were updated before the specified time.
- status: (Optional) Filters the results to return exports in the given state. Allowed values are "Complete", "Failed", "Processing", or "Waiting".
- object: (Optional) Filters the results to return exports for the specified object.
- sort_by: (Optional) Sorts the results by the specified property value. Allowed values are "id", "created_at", or "updated_at". If not specified, the results are returned by "id" in "descending" order.
- sort_order: (Optional) Used with
sort_by
. Adjusts the direction of the sort using the values "ascending" or "descending". If not specified, the results are in "descending" order.
Success
Status Code: 200
Output Representation
- result: A collection of exports
- total_results: The total number of results matching the filter.
- export: A collection of exports. If there are no results, this property is omitted. If there's a single result, it's an object. If there are multiple results, it's an array of results.
- id: The ID of the export. This ID is used to check the status of the export.
- state: The state of the export. Displays "Waiting" when the export has been queued for processing, "Processing" when the server is working on the export and "Complete" when the export has completed. See Export State enum.
- isExpired: Indicates that the export has expired. After an export has expired, this will return
true
and no data associated with the export can be downloaded. - createdAt: The date and time the export was created in the timezone of the user making the request.
- updatedAt: The date and time the export was updated in the timezone of the user making the request.
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
- Status Code: 4xx
- Error codes: See Error Codes & Messages
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
- Status code: 4xx
- Error codes: See Error Codes & Messages
Enums
Export State
- "Waiting": The export is waiting to be processed.
- "Processing": A server has started processing the export.
- "Complete": The export is complete and the results are available for download.
- "Failed": A fatal error has occurred and the data can’t be retrieved. Try executing the export again. If the error occurs again, contact support.