---
schema_version: "1"
id: 1279fd48d3d9472446114b8013cc9baa72fabaa57e63e974d73c24308108c8b5
title: POST /interaction/v1/interactions/journeyhistory/download
collection: developer
version: current
locale: en-us
portal_url: https://docs.salesforce.com/developer/current/en-us/marketing-cloud/guides/mc-apis/downloadJourneyHistory.md
canonical_url: https://developer.salesforce.com/docs/marketing/marketing-cloud/references/mc_rest_interaction/downloadJourneyHistory.html
source_site: developer.salesforce.com
content_type: documentation
content_hash: 663bcbd3757a3f9a92f5ef61382134c674cf78d3363dddf934aa0813954153d8
products:
  - Marketing Cloud Engagement APIs and Programmatic Languages
  - Marketing Cloud
---
# 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](https://developer.salesforce.com/docs/marketing/marketing-cloud/references/mc_rest_interaction/getJourneyHistoryDownloadEstimate.md) 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](https://developer.salesforce.com/docs/marketing/marketing-cloud/references/mc_rest_interaction/getJourneyHistoryDownloadEstimate.md) before you submit a journey history download request.

**note:** Before the Winter ’25 release, journey history downloads included rows where the activity name was empty and the status was Complete. These rows are no longer included. This change improves performance and prevents the success rate metrics from becoming artificially inflated.

## URL Parameters

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

## JSON Parameters

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.               | <ul><li>`abntest`</li><li>`abnteststop`</li><li>`activeaudiencejourneyactivity`</li><li>`einsteinengagementfrequencysplit`</li><li>`emailv2`</li><li>`engagementdecision`</li><li>`exitcriteriaactivity`</li><li>`goalcriteriaactivity`</li><li>`inappsyncactivity`</li><li>`multicriteriadecision`</li><li>`multicriteriadecisionextension`</li><li>`pushinboxactivity`</li><li>`pushnotificationactivity`</li><li>`pushsync`</li><li>`randomsplit`</li><li>`rest`</li><li>`restdecision`</li><li>`salescloudactivity`</li><li>`salesforceleadconversionactivity`</li><li>`sendtolinesync`</li><li>`smssync`</li><li>`startinteractionactivity`</li><li>`stopinteractionactivity`</li><li>`stowait`</li><li>`trigger`</li><li>`updatecontactdata`</li><li>`wait`</li><li>`waitactivity`</li><li>`waituntilapi`</li><li>`waituntilchatresponse`</li><li>`waituntilpushengagement`</li><li>`whatsappactivity`</li></ul>                                                                                                                                                                                                                                                                                                                                                                                         |
| `definitionIds`         | Array  | A list of journey IDs to retrieve events for.                  |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `statuses`              | Array  | A list of statuses to retrieve events for.                     | <ul><li>`Active`</li><li>`Complete`</li><li>`ContactAlreadyInInteraction`</li><li>`ContactExitedAsOutOfMarketAudienceSegment`</li><li>`ContactExitedByApi`</li><li>`ContactIsDeleted`</li><li>`ContactIsRestricted`</li><li>`ContactKeyNotProvided`</li><li>`ContactNotFound`</li><li>`ContactObjectNull`</li><li>`ContactPreviouslyInSameInteraction`</li><li>`ContactStatusIsUnknown`</li><li>`CouldNotParseInteractionId`</li><li>`CurrentlyWaitingInSameInteraction`</li><li>`Deactivated`</li><li>`DidNotMeetEntryCriteria`</li><li>`ErrorDeterminingInitialActivity`</li><li>`ErrorOccurredinProcessing`</li><li>`ErrorProcessingWaitActivity`</li><li>`ErrorValidatingContact`</li><li>`ExitCriteriaMet`</li><li>`Failed`</li><li>`GoalCriteriaAlreadyMet`</li><li>`GoalCriteriaMet`</li><li>`GoalCriteriaMetInWait`</li><li>`GoalCriteriaNotMet`</li><li>`GoalNotDefined`</li><li>`InteractionNotPublished`</li><li>`InvalidInteractionId`</li><li>`MetCriteria`</li><li>`MovedToHigherPriorityInteraction`</li><li>`NotEvaluatingEntryCriteria`</li><li>`StoppedByUser`</li><li>`UnableToDeserializeMessage`</li><li>`Unknown`</li><li>`WaitActivtyAlreadyProcessed`</li><li>`Waiting`</li><li>`WaitingForAsync`</li><li>`WaitUntilEventCriteriaMet`</li><li>`WaitUntilEventCriteriaNotMet`</li></ul> |
| `definitionInstanceIds` | Array  | A list of definition instance IDs to retrieve events for.      |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `activityIds`           | Array  | A list of activity IDs to retrieve events for.                 |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |

## Headers

| 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. | <ul><li>`gzip`</li><li>`deflate`</li></ul>You can also specify both methods. List multiple values in order of preference and separate them with a comma. For example, `gzip,deflate`. |

## Usage

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.

### Limit Results Based on Time

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

```
Host: https://YOUR_SUBDOMAIN.rest.marketingcloudapis.com
POST /interaction/v1/interactions/journeyhistory/download?columns=ActivityId,ContactKey
Authorization: Bearer YOUR_ACCESS_TOKEN
Content-Type: application/json
x-direct-pipe: true
{
   "start": "2023-07-11T06:00:00Z",
   "end": "2023-07-11T21:00:00Z",
   "definitionIds": ["58c2edb1-703e-45d8-9841-9e5d63ed1117"],
   "statuses": ["failed"]
}
```

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

```
ActivityId,ContactKey
730a1428-85c5-4779-ae56-b698b11e9744,TestContact-71
730a1428-85c5-4779-ae56-b698b11e9744,TestContact-19
a46f01f7-ebce-40bd-9a84-f71c32db7fe3,TestContact-22
```

### Limit Results Based on Status

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.

```
Host: https://YOUR_SUBDOMAIN.rest.marketingcloudapis.com
POST /interaction/v1/interactions/journeyhistory/download?columns=ContactKey
Authorization: Bearer YOUR_ACCESS_TOKEN
Content-Type: application/json
x-direct-pipe: true
{
  "definitionIds": ["2f859388-ccb7-4dc8-9101-2526c07b80da"],
  "status": "didnotmeetentrycriteria"
}
```

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

```
ContactKey
T-9999998
T-9999993
```

### Limit Results by Activity Type

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

```
Host: https://YOUR_SUBDOMAIN.rest.marketingcloudapis.com
POST /interaction/v1/interactions/journeyhistory/download?columns=ContactKey
Authorization: Bearer YOUR_ACCESS_TOKEN
Content-Type: application/json
x-direct-pipe: true
{
  "definitionIds": ["2f859388-ccb7-4dc8-9101-2526c07b80da"],
  "activityTypes": ["trigger"],
  "statuses": ["complete"]
}
```

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

```
ContactKey
T-0000001
T-0000002
T-0000003
```

### Download a Compressed File

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.

```
curl "https://YOUR_SUBDOMAIN.rest.marketingcloudapis.com/interaction/v1/interactions/journeyhistory/download" \
  -X POST \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "accept-encoding: gzip" \
  -H "x-direct-pipe: true" \
  -H "content-type: application/json" \
  -d '{
   "start": "2023-07-11T06:00:00Z",
   "end": "2023-07-11T21:00:00Z",
   "definitionIds": ["58c2edb1-703e-45d8-9841-9e5d63ed1117"],
   "statuses": ["failed"]
}'
```

The command returns a `.gz` file.

## Optimizing Download Requests

You can reduce file sizes by including the `accept-encoding: gzip, deflate` header in your request. If 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, it isn’t necessary to specify that column in the result. For example, if the response only includes failed events&mdash;that is, the request body includes `"statuses": ["failed"]`&mdash;use the `columns` query parameter to omit the `status` column from the result.
- Download data from a small 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.