Get processes (errors) by workflow

get/v1/workflows/{id}/processes
Requires any one of these rolesAbout roles
org.permission.workflow.read
Legacyorg.admin.workflow.read

The API key or user must hold at least one of them. Legacy roles still work; prefer the others for new keys.

Retrieves all of the processes (errors) for a given workflow based on the Workflow ID.

Workflow process attributes

In the sample response, you will notice that workflow processes (errors) have the following attributes that can help with troubleshooting an error:

  • Event: the original event that triggered the workflow. This is a raw internal representation of the data before the data is normalized by the workflow trigger.

  • Error: a stringified version of the error object that describes what went wrong. In some cases, this will say System Error – Retrying.

  • Meta.Context: contains a stringified version of the workflow context. This includes an order array of completed workflow steps and the inputs/outputs at each step.

  • Meta.WorkflowRev: reflects the revision (rev) or version of the workflow that generated the error. This is useful if the workflow has been fixed or has changed since the workflow first generated the error.

About this resource

Workflow processes (errors)

A workflow process is the record Kustomer keeps when a workflow run fails. It stores the event that started the run, the error, and the run's context up to the failure, so you can see what went wrong.

When a workflow run fails, Kustomer records a process for it. These are the same failures admins see under the Errors filter on the Workflows page, and the most recent one is also copied to the workflow's lastError. Runs that end normally, including runs where no transition matched, don't create a process. Neither do REST steps that get an error status from your service: the step succeeds, and your transitions decide what happens next.

Process records are kept for about a week, then removed. For a longer history, poll this endpoint and store the results yourself.

Reading a process

Attribute Meaning
status failed.
error A JSON string with message and step, the ID of the step that failed.
event The raw event that started the run, before the trigger normalized it into step 1.
meta.context A JSON string of the run's context: order lists the steps that ran, and steps.<id>.output holds each one's output. Variables are removed.
meta.workflowRev The workflow revision that ran. If it's older than the current one, the problem may already be fixed.
createdAt When the failure was recorded.

error and meta.context are strings, so parse them before reading. Runs that Kustomer retries after a temporary platform problem or a 5xx from a Kustomer action start again from step 1, so earlier steps run again. The debugging guide lists the other common messages and their fixes.

Which endpoint to use

To Call
List a workflow's failed runs GET /v1/workflows/{id}/processes
See only the latest failure lastError on GET /v1/workflows/{id}

Results are newest first by default (sort=asc reverses them) and paginated, 100 per page unless you set pageSize; meta.total and meta.totalPages tell you how many there are. createdAtFrom (inclusive) and createdAtTo (exclusive) take ISO 8601 dates to narrow the range, which is the easy way to fetch only failures since your last check. To watch a run step by step instead, including runs that didn't fail, open View Logs in the workflow builder.

RelatedDebugging and logsWorkflowsWorkflow JSON

Path parameters

idstringrequired

Workflow ID

Example "5b84680f6a3d70001b4c7183"

Query parameters

createdAtFromstring<date-time>

Date to filter results with a createdAt greater than or equal to date time in ISO 8601 format

Example "2023-12-14T00:00:00Z"
createdAtTostring<date-time>

Date to filter results with a createdAt less than date time in ISO 8601 format

Example "2023-12-14T00:00:00Z"
pagenumber

Number of pages to return for results. Default value: 1.

Example 1
pageSizenumber

Number of results to return per page. Default value: 100.

Default 100Example 100
sortstring

Sort order by createdAt. Defaults to desc (newest first).

One ofascdescDefault "desc"Example "desc"

Responses

OK

objectrequired
objectrequired
array<object>required