📩 Learning 7 - Finding Contacts from a Specific Journey Activity Using the Journey History Download API

Lakshmi Pavani

— 4 min read

Recently, I received a request to identify the subscribers who had passed through a specific activity within a Journey Builder Journey in Salesforce Marketing Cloud (SFMC).

My first instinct was to explore Journey Builder tracking, Data Views, and available reporting options. However, I quickly discovered that retrieving contacts for a specific journey activity wasn't as straightforward as I expected.

To get some guidance, I reached out to Salesforce Support.

During the discussion, the Support Engineer introduced me to something I hadn't worked with before: the Journey History Download API.

As someone who enjoys simplifying technical concepts through everyday examples, the whole process reminded me of something much closer to home — a busy South Indian breakfast preparation 😄.

And that's when the analogy clicked.

🍽️ The Scenario: Finding Out how many idlys were consumed

Imagine it's a busy Sunday morning at home.

Several items are being prepared simultaneously:

  • Idlis
  • Chutney/Sambar
  • Coffee
  • Other dishes may be for lunch

Everyone in the family is helping in the kitchen, and multiple cooking activities are happening at the same time.

Later, someone asks:

"How many idlis were prepared and consumed this morning?"

To answer that question, you don't need details about the lunch related dishes, coffee.

You only need to focus on:

  • The idli preparation process
  • The specific batch of idlis
  • The family members who consumed them

This is surprisingly similar to identifying contacts who passed through a specific activity within a Journey.

🏠 The Kitchen = Journey Builder

Think of the kitchen as Journey Builder.

Just as multiple dishes are being prepared simultaneously in a kitchen, multiple journeys, versions, and activities can be running within Journey Builder at the same time.

The challenge isn't accessing all the information.

It's identifying the exact activity you're interested in.

🥣 The Idlis = Journey Definition

Among all the food being prepared, you're interested only in the idlis.

Similarly, in Marketing Cloud you need to identify the specific journey you're investigating.

This is where the Journey Definition ID becomes important.

The Journey Definition helps narrow the search to the journey that matters.

📦 Today's Batch of Idlis = Specific Journey Version

The same idli recipe might be prepared every day. But today you're interested in a particular batch. Likewise, Journeys can have multiple versions.

When retrieving activity records, we often need data from a specific Journey Version, not from every version that has ever existed.

This is where the Definition ID helps us focus our search.

🥘 The Idli Steamer = Activity ID

A kitchen contains multiple utensils:

  • Idli steamer
  • Dosa pan
  • Pressure cooker
  • Coffee filter

If the question is about idlis, you ignore everything except the idli steamer.

Similarly, a Journey contains multiple activities:

  • Email Sends
  • SMS Sends
  • Wait Activities
  • Update Contact Activities
  • Exits

To identify the exact step we're interested in, we use the Activity ID.

The Activity ID helps isolate a single activity from all the other activities within the journey.

⏰ Breakfast Time = Date Range

Suppose you only want information about today's breakfast.

You don't want yesterday's records or last week's.

Similarly, the Journey History Download API allows you to define:

  • Start Date
  • End Date

These filters help limit the search to a specific timeframe and prevent unnecessary results from being returned.

✅ Breakfast Finished = Status Complete

You can only confirm who actually ate the idlis after breakfast has been completed.

The same concept applies within Journey Builder.

For my requirement, I only wanted contacts that had successfully completed the selected activity.

Using:

JSON"statuses": ["complete"]
Show more lines

ensures that only contacts with a completed activity status are returned.

📒 The Family Breakfast Notebook = Journey History Download API

Imagine someone maintained a notebook recording who was served idlis during breakfast.

Instead of asking every family member individually, you could simply check the notebook.

This is exactly what the Journey History Download API does.

It acts as the historical record keeper, allowing us to retrieve contacts that passed through specific Journey activities.

🔧 API Example

Endpoint

HTTPPOST https://{AUTHENTICATEDDOMAIN}.rest.marketingcloudapis.com/interaction/v1/interactions/journeyhistory/download?columns=ContactKey,Status

Request Body

JSON{
"start": "2026-07-06T06:00:00Z",
"end": "2026-07-07T21:00:00Z",
"ActivityId": [
"EMailActivityId"
],
"activityTypes": [
"emailv2"
],
"definitionIds": [
"JourneyDefinitionKey"
],
"statuses": [
"complete"
]
}

🔍 Understanding the Key Filters

Start and End

Defines the timeframe within which Journey activity records should be searched.

ActivityId

Identifies the specific Journey activity being analyzed.

ActivityTypes

Defines the activity type being filtered.

For example:

JSON"activityTypes": ["emailv2"]

focuses specifically on Email Activities.

DefinitionIds

Identifies the Journey Version to include in the search.

Statuses

Filters the activity records based on status.

For example:

JSON"statuses": ["complete"]

returns only successfully completed activities.

Columns

Determines which fields are returned in the output.

For example:

HTTP?columns=ContactKey,Status

returns only the Contact Key and Status values.

💡 What I Learned

When Salesforce Support first shared this endpoint with me, I initially viewed it as just another Journey API.

However, the real learning came from understanding how the filters work together.

By combining:

  • Journey Definition ID
  • Activity ID
  • Activity Type
  • Date Range
  • Status

I was able to narrow down the results and retrieve exactly the subscriber records I needed.

Just like identifying who consumed the idlis from a specific breakfast preparation, success wasn't about collecting all the kitchen data.

It was about focusing on the right dish, the right utensil, and the right timeframe.

📌 Key Takeaways for SFMC Practitioners

  • The Journey History Download API can be used to retrieve contact-level activity history from Journey Builder.
  • Journey Definition IDs help isolate the correct journey version.
  • Activity IDs help focus on a specific activity within a journey.
  • Date Range filters reduce unnecessary records and improve accuracy.
  • Status filtering (such as "complete") helps identify contacts that successfully passed through an activity.
  • The combination of multiple filters is what makes the API truly powerful.

🧭 Conclusion

Sometimes the challenge isn't accessing data — it's knowing how to filter it effectively.

Thinking about the Journey History Download API as tracking who consumed the idlis during breakfast helped me simplify the entire process.

Instead of looking at everything happening in the kitchen, I only needed to focus on:

  • A specific dish
  • A specific cooking vessel
  • A specific timeframe

Similarly, by defining the correct Journey Version, Activity ID, Date Range, and Status, the Journey History Download API can help retrieve the exact contacts that passed through a particular Journey activity.

So the next time someone asks for subscribers associated with a specific Journey activity, think of a busy breakfast kitchen - sometimes all you really need to know is who enjoyed the idlis! 😊

Note - These are simply my observations and learnings. Always refer to official Salesforce documentation and Salesforce Support guidance for the most accurate and up-to-date information.

Salesforce Help article: https://developer.salesforce.com/docs/marketing/marketing-cloud/references/mc_rest_interaction/downloadJourneyHistory.html

I hope you found these insights helpful. If you've used the Journey History Download API in a different way or have your own learnings to share, feel free to leave a comment below! 🚀

Read more