POST /interaction/v1/interactions/journeyhistory/download

Downloads journey history to a file. You can specify which fields are returned. The maximum file size is 1 GB, but you can use file compression to fit more data into a smaller file. To retrieve an estimate of the file size and row count, use the journey history download estimate request operation before you request the data.

Journey history data is retained for 30 days. Journey history downloads are limited to 1 GB and can’t be resumed. To save time and avoid repeating effort, we recommend that you request an estimate before you submit a journey history download request.

Starting with the Winter ’25 release, Journey history downloads won’t include rows where the activity name is empty and the status is Complete. This change improves performance and prevents the success rate metrics from becoming artificially inflated.

Name	Type	Description	Accepted Values
format	String	The format to use for the output file. The default value is csv.	csv tsv
columns	String	Comma-separated list of columns to download. The default value is TransactionTime, ContactKey, Status, DefinitionId, DefinitionName, ActivityId, ActivityName, ActivityType.	ActivityId ActivityName ActivityType ClientStatus ContactKey CreatedDate DefinitionId DefinitionInstanceId DefinitionName EndDate EntrySource EpochTimeInMilliseconds EventId EventName Id Message OutcomeActivityId SourceType StartDate Status TransactionTime Result.Messages Result.Outcome Result.Status Result.Tags

The request body can contain any of the values in this table.

Name	Type	Description	Possible Values
start	String	The start date and time for the query, in ISO 8601 format.
end	String	The end date and time for the query, in ISO 8601 format.
contactKeys	Array	A comma-separated list of contact keys to retrieve events for.
activityTypes	Array	A list of activity types to retrieve events for.	abntest abnteststop activeaudiencejourneyactivity einsteinengagementfrequencysplit emailv2 engagementdecision exitcriteriaactivity goalcriteriaactivity inappsyncactivity multicriteriadecision multicriteriadecisionextension pushinboxactivity pushnotificationactivity pushsync randomsplit rest restdecision salescloudactivity salesforceleadconversionactivity sendtolinesync smssync startinteractionactivity stopinteractionactivity stowait trigger updatecontactdata wait waitactivity waituntilapi waituntilchatresponse waituntilpushengagement whatsappactivity
definitionIds	Array	A list of journey IDs to retrieve events for.
statuses	Array	A list of statuses to retrieve events for.	Active Complete ContactAlreadyInInteraction ContactExitedAsOutOfMarketAudienceSegment ContactExitedByApi ContactIsDeleted ContactIsRestricted ContactKeyNotProvided ContactNotFound ContactObjectNull ContactPreviouslyInSameInteraction ContactStatusIsUnknown CouldNotParseInteractionId CurrentlyWaitingInSameInteraction Deactivated DidNotMeetEntryCriteria ErrorDeterminingInitialActivity ErrorOccurredinProcessing ErrorProcessingWaitActivity ErrorValidatingContact ExitCriteriaMet Failed GoalCriteriaAlreadyMet GoalCriteriaMet GoalCriteriaMetInWait GoalCriteriaNotMet GoalNotDefined InteractionNotPublished InvalidInteractionId MetCriteria MovedToHigherPriorityInteraction NotEvaluatingEntryCriteria StoppedByUser UnableToDeserializeMessage Unknown WaitActivtyAlreadyProcessed Waiting WaitingForAsync WaitUntilEventCriteriaMet WaitUntilEventCriteriaNotMet
definitionInstanceIds	Array	A list of definition instance IDs to retrieve events for.
activityIds	Array	A list of activity IDs to retrieve events for.

Name	Type	Description	Possible values
x-direct-pipe	Boolean	Required. To download journey history data, your request must include this header with a value of true.
accept-encoding	String	To compress the requested data, include this header. The value of the header determines the method that’s used to compress the resulting data. Using gzip compression typically results in a smaller file size.	gzip deflate You can also specify both methods. List multiple values in order of preference and separate them with a comma. For example, gzip,deflate.

To tailor the resulting file to your needs, include filters and query values in your request. You can also compress the resulting file to improve performance and minimize file sizes.

This example downloads all the contacts that failed to enter the journey between 06:00 and 21:00 UTC.

The response includes the fields that you specified in the columns parameter in the query path.

You can specify the contacts that are downloaded by changing the value of the status parameter. This request downloads a list of contacts that didn’t meet the entry criteria in the specified journey. The list is filtered to only include values in the ContactKey column.

The response includes the values in the ContactKey column for the records that didn’t meet the entry criteria.

This example downloads the list of contacts successfully injected into the given journey.

The response includes the values in the ContactKey column for the records that completed the trigger activity.

To download compressed files, use a data transfer client such as cURL or Wget. This example uses cURL to download journey history data in a gzip file.

The command returns a .gz file.

You can reduce file sizes by including the accept-encoding: gzip, deflate header in your request. When you include this header, the resulting output is smaller and therefore takes less time to download.

To further optimize your download requests, limit their scope. Use these tips to limit the scope of your download requests.

• If you only want to download information about a single journey, include the definitionId for that journey in the request.
• If you only want to download information about a single journey activity, include the activityId for the activity in the request.
• Use the columns query parameter to download only the columns that you need. This step reduces the download file size and the time required to complete the request.
• If your request contains filters that limit certain fields to a single value, including that column in the result isn’t necessary. For example, if the response only includes failed events—that is, the request body includes "statuses": ["failed"]—use the columns query parameter to omit the status column from the result.
• Download data from a small time period, such as 1 hour, by using the start and end parameters in the request body. This step results in better performance. If a download fails, requesting smaller units of data can save time and effort, because you can’t resume a failed download.
• If your request contains filters that limit certain fields to a single value, including that column in the result isn’t necessary. For example, if the response includes only failed events—that is, the request body includes "statuses": ["failed"]—use the columns query parameter to omit the status column from the result.
• Download data from a short time period, such as 1 hour, by using the start and end parameters in the request body. This step results in better performance. If a download fails, requesting smaller units of data can save time and effort, because you can’t resume a failed download.