Pardot's developer content is getting a makeover! Starting July 12th, you’ll be redirected to our new site.

Lifecycle History Resources

Use lifecycle history resources to learn how a prospect is moving through their sales journey, from visitor to won opportunity. Learn what stage they’re currently in, how long they’ve been in that stage, and where that stage sits in the overall sales journey. For information about lifecycle stages, see Lifecycle Stage Resources. Learn more about prospect lifecycles in Salesforce Help.

Note: Include the authentication header with every request. For information on how to authenticate, see Authentication.

Resource Name	Operation	Description
Lifecycle History Query	`GET`	Request information for lifecycle history records that match the specified criteria.
Lifecycle History Read	`GET`	Request information for a single lifecycle history record.

Lifecycle History Query

Request information for the lifecycle history records that match the specified criteria. You can specify the lifecycle history records and fields to request. A maximum of 200 records are returned. To return all lifecycle history records, specify the output as mobile.

URI

/api/lifecycleHistory/version/3/do/query?...

Parameters to Select Lifecycle History Records

Use these parameters to specify the lifecycle history records to return. Parameters can be used in any combination and in any order unless otherwise specified.

Notes:

Parameters must be URL-encoded.
Dates and times must use GNU Date Input Syntax (for example, yyyy-mm-dd:hh:ss:mm).
For a full listing of lifecycle history fields, see Object Field References.

Parameter	Type	Possible Values	Description
`created_after`	`string`	`today`, `yesterday`, `last_7_days`, `this_month`, `last_month`,`<custom_time>`	Request lifecycle history records created after the specified time. Example: To request lifecycle history records created in 2020, use `/api/lifecycleHistory/version/3/do/query?created_after=2019-12-31 24:59:59`.
`created_before`	`string`	`today`, `yesterday`, `last_7_days`, `this_month`, `last_month`, `<custom_time>`	Request lifecycle history records created before the specified time. Doesn’t include lifecycle history records created at the specified time. Example: To request lifecycle history records created before today (but not created today), use `/api/lifecycleHistory/version/3/do/query?created_before=today`.
`id_greater_than`	`integer`	Any positive integer	Request lifecycle history records that have an ID greater than the specified number.
`id_less_than`	`integer`	Any positive integer	Request lifecycle history records that have an ID less than the specified number.

Parameters to Specify Which Results Are Returned

Use these parameters to specify the lifecycle history fields to return, and how the lifecycle history records are sorted.

Parameter	Type	Possible Values	Description
`limit`	`integer`	Any integer from 1 through 200.	The number of lifecycle history records to return. Default value is 200.
`offset`	`integer`	Any positive integer	The number of lifecycle history records to omit from the response (the number to "skip over"). Example: Retrieve a list of lifecycle history records, omitting the 50 most recently updated records. Sort the query by the `ID` field and use offset=50: `/api/lifecycleHistory/version/3/do/query?sort_by=id&offset=50`
`sort_by`	`string`	`created_at`, `id`	The field by which the results are sorted. See Sort Order.
`sort_order`	`string`	`ascending, descending`	The sort order. The default value depends on which `sort_by` parameter you specify. See Sort Order.

Sort Order

Use sort_by to specify which field Pardot uses to sort the results. Different fields have different default sort orders.

Value	Default Sort Order	Description
`created_at`	descending	Sort the results by the lifecycle history records' `created_at` timestamps.
`id`	ascending	Sort the results by the lifecycle history records' `id` fields.

Lifecycle History Read

Request information for a single lifecycle history record.

URI

/api/lifecycleHistory/version/3/do/read/id/<ID>

Replace <ID> with the Pardot ID of the lifecycle history record.

Example

Request information about the lifecycle history record with ID 1234.

/api/lifecycleHistory/version/3/do/read/id/1234

XML Response

The XML response for a query request contains information for multiple lifecycle history records. The XML response for a read request contains information for a single lifecycle history record.

XML Response for a Lifecycle History Query

<rsp stat="ok" version="1.0">
    <result>
        <total_results>...</total_results>
        <lifecycleHistory>...</lifecycleHistory>
        <lifecycleHistory>...</lifecycleHistory>
        <lifecycleHistory>...</lifecycleHistory>
    </result>
</rsp>

Tag	Description
`<result>`	Parent tag. Contains the lifecycle history records that match the parameters specified in your query.
`<total_results>`	Contains the number of lifecycle history records selected by the query. Note The query request returns a maximum of 200 lifecycle history records. If your query matches more than 200 records, you can make several requests to retrieve all matching records.
`<lifecycleHistory>`	The information about a single lifecycle history record. See Lifecycle History in Object Field References for a complete description of fields.

XML Response for a Lifecycle History Read

<?xml version="1.0" encoding="UTF-8"?>
<rsp stat="ok" version="1.0">
    <lifecycleHistory>
        <id>1234567890</id>
        <prospect_id>12345</prospect_id>
        <previous_stage_id/>
        <next_stage_id>6789</next_stage_id>
        <seconds_elapsed/>
        <created_at>2021-10-11 12:17:08</created_at>
    </lifecycleHistory>
</rsp>

Tag	Description
`<lifecycleHistory>`	Contains a single lifecycle history record. See Lifecycle History in Object Field References for a description of fields.