run_workflow
Trigger a workflow run. Runs are asynchronous — poll with get_run_status to retrieve the output.
Parameters#
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
workflow_id | string | yes | Workflow id | |
input_data | string | object | null | no | {} | Input matching the workflow’s input_schema. String values are parsed as JSON when possible; otherwise treated as raw input. |
target | string | null | no | null | What to run. Omitted: the production release when one is pinned, else the workflow itself (what schedules and the API run). Or "draft" (the working copy, even when a release is pinned), "production", or a release_... id. |
Returns#
json
{
"run_id": "agent_run_xyz",
"status": "pending"
}| Field | Description |
|---|---|
run_id | Pass to get_run_status to poll |
status | Initial status: usually pending. Typical path: pending → running → completed |
Errors#
error_type | When |
|---|---|
auth_error | Missing / invalid API key |
not_found | Workflow id doesn’t exist or is outside your org |
invalid_input | Input failed the workflow’s trigger-schema validation |
execution_error | Couldn’t dispatch the run (rare — usually transient) |
Example#
Request:
json
{
"workflow_id": "agent_abc",
"input_data": { "email": "lead@example.com" }
}Response:
json
{ "run_id": "agent_run_xyz", "status": "pending" }Then poll get_run_status until status is completed or failed.
See also#
get_workflow— inspectinput_schemabefore callingget_run_status— poll for completion