Step 6: Fetch journey state

Fetching the journey state allows you to track the progress of a journey instance. It helps you determine whether the journey is still in progress, has completed, or requires further input from the customer.

​

When to fetch the journey state

You should check the journey:

• After starting a journey – to confirm it was created successfully
• After submitting task data – to see if the journey progressed or completed
• To monitor progress – during multi-step journeys with multiple tasks
• Before triggering next steps – some workflows depend on the journey being completed
• For troubleshooting – to identify if the journey has stalled

​

What you need before fetching

Make sure you have:

• Access token – Refer to Authenticate
• Instance ID – Returned from Start a journey

​

API request to fetch state

Send a POST request to the /journey/state/fetch endpoint. Your request should follow this format:

curl --request POST \
  --url https://eu.platform.go.gbgplc.com/captain/api/journey/state/fetch \
  --header 'Authorization: Bearer your_access_token' \
  --header 'Content-Type: application/json' \
  --data '{
    "instanceId": "your-instance-id"
  }'

If your request is successful, you receive a response in this format:

{
  "instanceId": "c8c6fabc-1f24-491f-bf1b-347b95cb88fa",
  "state": "COMPLETED",
  "timestamp": "2025-03-26T14:22:10Z",
  "lastUpdated": "2025-03-26T14:25:45Z"
}

Refer to the Fetch journey state API reference for details on the request and response definitions.

​

What happens next?

Depending on the state:

​

Best practices

• Periodically check the state for long-running journeys.
• Always handle FAILED states gracefully and retry if appropriate.
• Use the COMPLETED state to trigger downstream business logic.

​

Next steps

• If the journey is complete, your integration is done.
• If you encountered an error, refer to the Handle errors guide for troubleshooting tips.