# On-Demand Journey Execution

On-Demand Journey Execution lets you trigger a batch journey immediately, using the most recently completed segment data, without waiting for a Parent Segment refresh to complete.

By default, a batch journey runs only after its associated Parent Segment refresh finishes. This works well for scheduled daily campaigns but creates delays when you need to act quickly — for example, after updating a segment rule or launching a time-sensitive campaign. On-demand execution removes that dependency.

On-demand execution is available today via the API and the `tdx` CLI. Treasure AI Studio users can trigger a journey using natural language — see [Using Treasure AI Studio](#using-treasure-ai-studio) below. A **Run Now** button in the Treasure AI UI is planned for a future release.

## When to use it

- You've updated a segment rule and want the journey to execute immediately
- You want to run a journey at a specific time, independent of the data refresh schedule
- You're building an automated pipeline that triggers journeys programmatically


## Before you start

Verify the following before triggering an on-demand run:

| Condition | What to do if it's not met |
|  --- | --- |
| Journey is active (not paused or draft) | Activate the journey from the Treasure AI UI |
| Journey has been refreshed at least once | Run a full data refresh first |
| No data refresh is currently running | Wait for the refresh to complete, then retry |
| Journey is not already running | Wait for the current execution to finish |
| Journey is not part of a Priority Group | Priority Group journeys are not supported — see [Limitations](#limitations) |


## How to trigger a run

### Using Treasure AI Studio

Treasure AI Studio can trigger a journey on your behalf using natural language. Provide the journey ID or paste the journey's console URL — Studio will resolve the ID and run `tdx journey run` in the background.

Example prompts:

```
Run journey 123.
```

```
Trigger this journey: https://console.treasuredata.com/app/workflows/journeys/123
```

```
Run the Black Friday campaign journey (ID 456) now.
```

Studio confirms when the journey has started and returns a session ID you can use to monitor progress.

### Using the TDX CLI

```sh
tdx journey run <journey_id>
```

Example:

```sh
tdx journey run 123
```

The command confirms the journey has started and returns a session ID:

```
Journey execution started.

Journey ID:          123
Workflow Session ID: 200
Status:              running

Monitor progress:
  tdx wf sessions 200
```

The command exits immediately — it does not wait for the journey to finish.

### Using the API

```
POST /entities/journeys/{journeyId}/run
```

Use the API base URL for your region. See [Treasure API Endpoints and Base URLs](/apis/endpoints/endpoints) for the full list.

Include your API key in the request header:

```sh
curl -X POST \
  https://api-cdp.treasuredata.com/entities/journeys/123/run \
  -H "Authorization: TD1 <your_api_key>" \
  -H "Content-Type: application/json"
```

Example response:

```json
{
  "data": {
    "id": "100",
    "type": "execution-journey",
    "attributes": {
      "journeyId": "123",
      "workflowSessionId": "200",
      "createdAt": "2026-05-07T00:00:00+00:00",
      "status": "running"
    }
  }
}
```

Save the `workflowSessionId` to monitor the run in the Treasure AI Workflow console.

## What to expect

**Your audience data is current, but not real-time.** The journey uses the data from the last completed Parent Segment refresh. If your refresh runs nightly, an on-demand run at noon uses last night's data. Changes that arrived after the last refresh — new opt-outs, updated profiles — won't be reflected until the next refresh completes.

**Segment rule changes take effect immediately.** If you've edited a segment rule, that change applies to the next run, including an on-demand run. You don't need to wait for a full data rebuild.

**Exception:** If you've made structural changes to the Parent Segment configuration — such as adding a new data source, attribute, or behavior definition — those changes require a full refresh before they're reflected in any journey run.

**Downstream activations fire normally.** Any actions configured to run after the journey completes (emails, exports, CRM updates) will execute just as they would after a scheduled run.

**Triggering one version runs all versions.** If your journey has multiple versions, triggering the latest version automatically runs older versions in sequence after it completes — the same behavior as a scheduled run.

## Error reference

If the run doesn't start, the API returns an error with a reason code:

| Error | What it means | What to do |
|  --- | --- | --- |
| `PARENT_SEGMENT_RUNNING` | A data refresh is currently in progress | Wait for the refresh to finish, then try again |
| `JOURNEY_WORKFLOW_RUNNING` | The journey is already running | Wait for the current run to complete |
| `JOURNEY_NOT_ACTIVE` | The journey is paused or in draft | Activate the journey in the Treasure AI UI first |
| `PRIORITY_GROUP_JOURNEY_NOT_ELIGIBLE` | Journey uses Priority Groups | Not supported — see [Limitations](#limitations) |
| `NOT_LATEST_VERSION` | The journey ID is an older version | Use the latest version's journey ID |
| `PARENT_SEGMENT_NEVER_REFRESHED` | The audience data has never been built | Run a full data refresh first |


## Automating on-demand runs

You can trigger on-demand journey runs from a Treasure Workflow using the `http>` operator. This lets you schedule or chain journey execution entirely within Treasure AI — no external scripts or cron jobs required.

**Example: trigger a journey on demand from a workflow**

```yaml
timezone: UTC

schedule:
  daily>: "06:00:00"

+run_journey:
  http>: https://api-cdp.treasuredata.com/entities/journeys/123/run
  method: POST
  content_type: application/json
```

Store your API key as a workflow secret so it is never hardcoded:

```sh
tdx wf secrets --set http.authorization="TD1 your_api_key_here" --project your_project_name
```

The `http.authorization` secret is automatically included in every `http>` request in the project as the `Authorization` header.

**Handling conflicts:** If the journey or Parent Segment is already running when the workflow fires, the API returns a `409` error and the workflow attempt fails. Add a retry policy to handle transient conflicts:

```yaml
+run_journey:
  http>: https://api-cdp.treasuredata.com/entities/journeys/123/run
  method: POST
  content_type: application/json
  _retry: 3
```

See the [Treasure Workflow documentation](/products/customer-data-platform/data-workbench/workflows) for full configuration options.

```

## Limitations

- **Priority Group journeys are not supported.** Priority Groups require coordinating across multiple journeys during a data refresh — this can't be replicated in a single on-demand run.
- **Structural data changes need a full rebuild first.** If you've added new data sources or changed the structure of your Parent Segment, run a full refresh before triggering an on-demand run.
- **No UI button yet.** The Run Now button is planned for a future release. For now, use Treasure AI Studio, the CLI, or the API.

## Related pages

- [Journey Workflow Dependencies](</products/customer-data-platform/journey-orchestration/Batch/journey-workflow-dependencies.md>) — how Parent Segment, journey, and activation workflows interact by default
- [Creating a Batch Journey](</products/customer-data-platform/journey-orchestration/Batch/creating-a-batch-journey.md>)
- [Pausing and Resuming a Journey](</products/customer-data-platform/journey-orchestration/Batch/pausing-and-resuming-a-journey.md>)
- [Treasure API Endpoints and Base URLs](</apis/endpoints/endpoints.md>)
```