Skip to main content
POST
Run a Workflow and wait
A 200 holds the finished run with outputs. A 202 means the run is still going: poll GET /v1/workflow-runs/{run_id} at its status_url.

Authorizations

Authorization
string
header
required

API key with the vd_sk_ prefix. Create keys from Settings, API Keys in the dashboard.

Headers

Idempotency-Key
string

Retry-safe key. The same key from the same account returns the run it already started.

Path Parameters

slug
string
required

The workflow's slug (shown on its API tab).

Query Parameters

wait
integer

Overrides wait in the body.

Required range: 0 <= x <= 120

Body

application/json
inputs
object

The workflow's inputs (see input_schema). Values are converted like skill inputs: "5" → 5 for an integer.

wait
integer

/run only: seconds to wait (default 60).

Required range: 0 <= x <= 120
webhook_url
string<uri>

Receives the finished run as a signed POST (X-Valendata-Signature).

Response

The finished run.

run_id
string
required
status
enum<string>
required
Available options:
pending,
running,
completed,
failed,
cancelled,
paused,
waiting_for_human
workflow_id
string
workflow_slug
string
inputs
object
outputs
object | null

{rows, count} from the final step. When several steps end the workflow: one {rows, count} per final step, keyed by step name. null while running.

error
string | null
diagnosis
object | null
created_at
string<date-time>
started_at
string<date-time> | null
finished_at
string<date-time> | null
execution_time_ms
integer | null
credits_charged
number
cost_usd
number
cost_final
boolean
cost_estimate_credits
number
steps
object[]
source
enum<string> | null
Available options:
api,
mcp
status_url
string