EndpointsWorkflow

Update Workflow Run

You can update the name and metadata of an in progress WorkflowRun at any time using this endpoint.

Authentication

AuthorizationBearer

Bearer authentication of the form Bearer <token>, where token is your auth token.

Path parameters

idstringRequired

The ID of the workflow run.

Example: "workflow_run_xKm9pNv3qWsY_jL2tR5Dh"

Headers

x-extend-api-version"2026-02-09"Optional

API version to use for the request. If you’re using an SDK, you can ignore this parameter. If you are not using an SDK and do not specify a version, you will either receive a 400 Bad Request or be set to a previous legacy version. See API Versioning for more details.

Request

This endpoint expects an object.
namestringOptional
An optional name that can be assigned to a specific WorkflowRun
metadatamap from strings to anyOptional
A metadata object that can be assigned to a specific WorkflowRun. If metadata already exists on this WorkflowRun, the newly incoming metadata will be merged with the existing metadata, with the incoming metadata taking field precedence. You can include any arbitrary `key : value` pairs in this object. To categorize workflow runs for billing and usage tracking, include `extend:usage_tags` with an array of string values (e.g., `{"extend:usage_tags": ["production", "team-eng", "customer-123"]}`). Tags must contain only alphanumeric characters, hyphens, and underscores; any special characters will be automatically removed.

Response

Successfully updated workflow run
objectenum

The type of object. In this case, it will always be "workflow_run".

Allowed values:
idstring

The ID of the workflow run.

Example: "workflow_run_xKm9pNv3qWsY_jL2tR5Dh"

workflowobject
workflowVersionobject
dashboardUrlstring

A URL to view this workflow run in the Extend dashboard.

Example: "https://dashboard.extend.ai/workflows/workflow_run_xKm9pNv3qWsY_jL2tR5Dh"

statusenum
The status of a workflow run: * `"PENDING"` - The workflow run is waiting to be processed * `"PROCESSING"` - The workflow run is currently processing * `"NEEDS_REVIEW"` - The workflow run requires manual review * `"REJECTED"` - The workflow run was rejected during review * `"PROCESSED"` - The workflow run completed successfully * `"FAILED"` - The workflow run encountered an error * `"CANCELLED"` - The workflow run was cancelled * `"CANCELLING"` - The workflow run is being cancelled
metadatamap from strings to any
The metadata that was passed in when running the Workflow.
batchIdstring or null

The batch ID of the WorkflowRun. If this WorkflowRun was created as part of a batch of files, all runs in that batch will have the same batch ID.

Example: "batch_7Ws31-F5"

fileslist of objects
failureReasonstring or null
The reason why the workflow run failed. Will only be included if the workflow run status is "FAILED".
failureMessagestring or null
A more detailed message about the failure. Will only be included if the workflow run status is "FAILED".
initialRunAtstring or nullformat: "date-time"

The time (in UTC) at which the workflow run was created. Will follow the RFC 3339 format. Will be null if the run hasn’t started yet.

Example: "2025-04-28T17:01:39.285Z"

reviewedByUserstring or null

The email address of the person who reviewed the workflow run. Will be null if the workflow run has not been reviewed.

Example: "jane.doe@example.com"

reviewedboolean
Whether the workflow run has been reviewed.
rejectionNotestring or null

A note that is added if a workflow run is rejected.

Example: "Invalid invoice format"

reviewedAtstring or nullformat: "date-time"

The time (in UTC) at which the workflow run was reviewed. Will follow the RFC 3339 format. Will be null if the workflow run has not been reviewed.

Example: "2024-03-21T16:45:00Z"

startTimestring or nullformat: "date-time"

The time (in UTC) at which the workflow run started executing. This will always be after the initialRunAt time. Will follow the RFC 3339 format. Will be null if the workflow run has not started executing.

Example: "2024-03-21T15:30:00Z"

endTimestring or nullformat: "date-time"

The time (in UTC) that the workflow finished executing. Will follow the RFC 3339 format. Will be null if the workflow run has not finished executing.

Example: "2024-03-21T15:35:00Z"

stepRunslist of objects
An array of WorkflowStepRun objects. Each WorkflowStepRun represents a single run of a WorkflowStep and contains details about the step's execution and result.
usageobject or null
Usage credits consumed by a run. **Availability:** This field will not be returned for: * Runs created before October 7, 2025 * Customers on legacy billing systems For more details on how credits work, see our [Credits Guide](https://docs.extend.ai/2026-02-09/product/general/how-credits-work).

Errors