Menu

Workflows Executions API Routes

These API routes allow you to track workflow executions in your MedusaGo application.

Depending on the workflow engine you use, executions may only be retained for a short while, or only until the MedusaGo application is restarted.

GET /admin/workflows-executions#

List Workflows Executions

Retrieve a list of workflows executions. The workflows executions can be filtered by fields such as id. The workflows executions can also be sorted or paginated.

Authentication: secret API key (HTTP Basic authorization), cookie session, JWT bearer token.

Query parameters

fieldsstringOptional
Comma-separated fields that should be included in the returned data. if a field is prefixed with + it will be added to the default fields, using - will remove it from the default fields. without prefix it will replace the entire default fields.
offsetnumberOptional
The number of items to skip when retrieving a list.
limitnumberOptional
Limit the number of items returned in the list.
orderstringOptional
The field to sort the data by. By default, the sort order is ascending. To change the order to descending, prefix the field name with -.
transaction_idstring | string[]Optional
Filter by a transaction ID.
workflow_idstring | string[]Optional
Filter by a workflow ID.
qstringOptional
Search query to filter by a workflow execution's searchable fields.
with_deletedbooleanOptional
Whether to include deleted records in the result.
statestring | string[]Optional
Filter by a workflow execution's state.
created_atobjectOptional
Filter by the workflow execution's creation date. Accepts the filter operators.

Request examples

Responses

200 OK

limitnumber
The maximum number of items returned.
offsetnumber
The number of items skipped before retrieving the returned items.
countnumber
The total number of items.
workflow_executionsobject[]
The workflows execution's workflow executions.

400, 401, 404, 409, 422, 500: an error response is returned.

GET /admin/workflows-executions/{id}#

Get a Workflows Execution

Retrieve a workflows execution by its ID. You can expand the workflows execution's relations or select the fields that should be returned.

Authentication: secret API key (HTTP Basic authorization), cookie session, JWT bearer token.

Path parameters

idstring
The workflows execution's ID.

Query parameters

fieldsstringOptional
Comma-separated fields that should be included in the returned data. if a field is prefixed with + it will be added to the default fields, using - will remove it from the default fields. without prefix it will replace the entire default fields.

Request examples

Responses

200 OK

workflow_executionobject
The workflows execution's details.

400, 401, 404, 409, 422, 500: an error response is returned.

POST /admin/workflows-executions/{workflow_id}/run#

Execute a Workflow

Execute a workflow by its ID.

Authentication: secret API key (HTTP Basic authorization), cookie session, JWT bearer token.

Path parameters

workflow_idstring
The workflow's ID.

Request body (application/json)

inputanyOptional
The input to pass to the workflow. Can be of any type.
transaction_idstringOptional
The ID of the workflow execution's transaction.

Request examples

Responses

200 OK

acknowledgementobject
The workflow's details

400, 401, 404, 409, 422, 500: an error response is returned.

POST /admin/workflows-executions/{workflow_id}/steps/failure#

Fail a Step in a Workflow's Execution

Set the status of a step in a workflow's execution as failed. This is useful for long-running workflows.

Authentication: secret API key (HTTP Basic authorization), cookie session, JWT bearer token.

Path parameters

workflow_idstring
The workflows execution's workflow id.

Request body (application/json)

transaction_idstring
The workflows execution's transaction ID.
step_idstring
The ID of the step whose status was changed.
responseanyOptional
Sets the step's response. It accepts any type.
compensate_inputanyOptional
Sets the compensation function's input. It accepts any response.
action"invoke" | "compensate"Optional
Whether to invoke or compensate the step.

Request examples

Responses

200 OK

successboolean
Whether the workflow step has failed successfully.

400, 401, 404, 409, 422, 500: an error response is returned.

POST /admin/workflows-executions/{workflow_id}/steps/success#

Succeed a Step in a Workflow's Execution

Set the status of a step in a workflow's execution as successful. This is useful for long-running workflows.

Authentication: secret API key (HTTP Basic authorization), cookie session, JWT bearer token.

Path parameters

workflow_idstring
The workflows execution's workflow id.

Request body (application/json)

transaction_idstring
The workflows execution's transaction ID.
step_idstring
The ID of the step whose status was changed.
responseanyOptional
Sets the step's response. It accepts any type.
compensate_inputanyOptional
Sets the compensation function's input. It accepts any response.
action"invoke" | "compensate"Optional
Whether to invoke or compensate the step.

Request examples

Responses

200 OK

successboolean
Whether the workflow step was succeeded.

400, 401, 404, 409, 422, 500: an error response is returned.

GET /admin/workflows-executions/{workflow_id}/subscribe#

Subscribe to a Workflow's Execution

Subscribe to a workflow's execution to receive real-time information about its steps, status, and data. This route returns an event stream that you can consume using the EventSource API.

Authentication: secret API key (HTTP Basic authorization), cookie session, JWT bearer token.

Path parameters

workflow_idstring
The workflows execution's workflow id.

Request examples

Responses

200 Stream of the step's status. The response body has the content type text/event-stream.

400, 401, 404, 409, 422, 500: an error response is returned.

GET /admin/workflows-executions/{workflow_id}/{transaction_id}#

Get Workflow Execution's Details

Get the details of the workflow's execution.

Authentication: secret API key (HTTP Basic authorization), cookie session, JWT bearer token.

Path parameters

workflow_idstring
The workflows execution's workflow id.
transaction_idstring
The workflows execution's transaction id.

Query parameters

fieldsstringOptional
Comma-separated fields that should be included in the returned data. if a field is prefixed with + it will be added to the default fields, using - will remove it from the default fields. without prefix it will replace the entire default fields.

Request examples

Responses

200 OK

workflow_executionobject
The workflows execution's details.

400, 401, 404, 409, 422, 500: an error response is returned.

GET /admin/workflows-executions/{workflow_id}/{transaction_id}/subscribe#

Subscribe to Workflow Execution Events

Subscribe to workflow execution events for a specific workflow and transaction. This endpoint establishes a Server-Sent Events (SSE) connection, allowing clients to receive real-time updates about the workflow execution. The events include details such as the event type, workflow ID, transaction ID, step information, response, result, and any errors that occur during the execution.

Authentication: secret API key (HTTP Basic authorization), cookie session, JWT bearer token.

Path parameters

workflow_idstring
The ID of the workflow to subscribe to.
transaction_idstring
The ID of the workflow execution transaction to subscribe to.

Request examples

Responses

200 OK

400, 401, 404, 409, 422, 500: an error response is returned.

Found a problem with this page?Report Issue
Edited Nov 14·Edit this page