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.

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 isn’t 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. See the visitor activity fields that are available for visitor activity. The value for fields must be an array of strings of the available fields.

Abilities
ActionRequirements
Create exportProspects > Visitors > View ability
View exportProspects > Visitors > View ability and be the same user that created the export
View all exportsAdmin > Exports > View ability
Query exportsAdmin > 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 isn’t specified, then no upper boundary is used in the query, and all data after the created_after is returned. The value can be today, 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 isn’t 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. Type Session is omitted.
  • prospect_only: (Optional) Selects only those visitor activities associated with a prospect. When this field is set to false, all visitor activities with and without a prospect are returned. The values can be true or false.

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 isn’t specified, then no upper boundary is used in the query, and all data after the updated_after is returned. The value can be today, 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 isn’t 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. Type Session is omitted.
  • prospectOnly: (Optional) Selects only those visitor activities associated with a prospect. When this field is set to false, all visitor activities with and without a prospect are returned. The values can be true or false.

NOTE: The range between updated_after and updated_before can’t exceed 1 year. When updated_before isn’t specified, the current date is used to gauge the interval.

List Membership

Fields

Select the fields that you want to export. See the fields that are available. The value for fields must be an array of strings of the available fields.

Abilities

ActionRequirements
Create exportMarketing > Segmentation > Lists > View ability and Prospects > Visitors > View ability
View exportMarketing > Segmentation > Lists > View ability and Prospects > Visitors > View ability and ability and be the same user that created the export
View all exportsAdmin > Exports > View ability
Query exportsAdmin > 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 membership that were created before the specified time. This value must be after the value in created_after. If this argument isn’t specified, then no upper boundary is used in the query, and all data after the created_after is returned. The value can be today, 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 whether it’s deleted or not. The value can be true, false, or all.

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 isn’t specified, then no upper boundary is used in the query, and all data after the updated_after is returned. The value can be today, 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 whether it’s deleted or not. The value can be true, false, or all.

NOTE: The range between created_after and created_before or updated_after and updated_before can’t exceed 1 year. When created_before isn’t specified, the current date is used to gauge the interval.

Prospect

Fields

Select the prospect fields that you want to export. See the prospect fields that are available. The value for fields must be an array of strings of the available fields.

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
ActionRequirements
Create exportProspects > Visitors > View ability
View exportProspects > Visitors > View ability and be the same user that created the export
View all exportsAdmin > Exports > View ability
Query exportsAdmin > 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 the updated_after is returned. The value can be today, yesterday, last_7_days, this_month, last_month, or a custom time specified in GNU Date Input Syntax format.
  • deleted: (Optional) Selects prospect based on if it is deleted or not. The value can be true, false, or all.

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. See prospect account fields that are available for prospect account. The value for fields must be an array of strings of the available fields.

Abilities
ActionRequirements
Create exportProspects > Prospect Accounts > View ability
View exportProspects > Prospect Accounts > View ability and be the same user that created the export
View all exportsAdmin > Exports > View ability
Query exportsAdmin > 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 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 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 the prospect_updated_after is returned. 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_deleted: (Optional) Selects prospect account based on whether it is associated with a prospect that has been deleted. The value can be true, false, or all. Default value is false.

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 the updated_after is returned. The value can be today, 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, or all. Default value is false.

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. See the vistor fields that are available. The value for fields must be an array of strings of the available fields.

Abilities
ActionRequirements
Create exportProspects > Visitors > View ability
View exportProspects > Visitors > View ability and be the same user that created the export
View all exportsAdmin > Exports > View ability
Query exportsAdmin > 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 the prospect_updated_after is returned. 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_deleted: (Optional) Selects visitor based on whether it is associated with a prospect that has been deleted. The value can be true, false, or all. Default value is false.

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 the updated_after is returned. The value can be today, 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, or all. Default value is false.

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

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 are 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 are used.

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 returns true and no data related 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’s no data associated with the export, this property is absent. If there’s 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.

Errors

Example

Here’s 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.

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.


Read

Used to retrieve the status of the export. When 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’s no data associated with the export, this property is absent. If there’s 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 isn’t 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.

Errors

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.

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

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


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.

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

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


Cancel

Used to cancel the export. If the export is already completed or failed, it can't be canceled.

POST

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. See Export State enum.
  • isExpired: Indicates that the export has expired. After an export has expired, this returns 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.

Errors

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 Cancel endpoint.

If the export is not already completed or failed, it is canceled.

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.
  • "Canceled": The export is canceled and can't be restarted.