Create Workflow Run

Trigger a new asynchronous run for a specific workflow.

POST /workflow-service/api/public/v1/workflows/{workflowId}/runs

Create Workflow Run

cURL

curl --request POST \
  --url https://api.slatehq.ai/workflow-service/api/public/v1/workflows/{workflowId}/runs \
  --header 'Authorization: <authorization>' \
  --header 'Content-Type: application/json' \
  --data '{
  "inputs": {}
}'

200

{
  "run_id": "<string>",
  "status": "<string>",
  "workspace_id": 123,
  "workflow_execution_id": "<string>",
  "status_url": "<string>"
}

Starts a new run for the specified workflow. The run is queued and processed asynchronously. Use the Get Run Status endpoint to poll for progress.

Parameters

workflowId · string · required

Unique identifier for the workflow to run. Find this in the Slate dashboard under the workflow’s settings.

Authorization · string · required

Bearer token. Format: Bearer slat_<your-token>.

Idempotency-Key · string

Optional unique key to prevent duplicate runs. If you send the same key with the same workflowId, the API returns the existing run instead of creating a new one. A key reused with a different workflowId returns a 409 error.

inputs · object · required

Key-value pairs that map to the workflow’s input parameters. The required keys depend on the specific workflow.

Response

Returns 202 Accepted with the queued run details.

run_id · string · required

Unique identifier for the created run. Use this to poll status or cancel the run.

status · string · required

Initial status of the run. Always QUEUED for new runs.

workspace_id · number

Workspace ID assigned to the run. May be null until the run starts processing.

workflow_execution_id · string

Internal execution ID. May be null until the run starts processing.

status_url · string · required

Relative URL to poll the run status. Append to the base URL to get the full path.

Example

cURL

curl -s -X POST "https://api.slatehq.ai/workflow-service/api/public/v1/workflows/wf_abc123/runs" \
  -H "Authorization: Bearer slat_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: my-unique-key-001" \
  --data-raw '{
    "inputs": {
      "brandDomain": "example.com"
    }
  }'

Response

{
  "run_id": "8c5e0f8a-2b35-4c1f-9b6a-9d0a6b3c1f4e",
  "status": "QUEUED",
  "workspace_id": null,
  "workflow_execution_id": null,
  "status_url": "/workflow-service/api/public/v1/workflow-runs/8c5e0f8a-2b35-4c1f-9b6a-9d0a6b3c1f4e"
}

Status codes

Status	Description
202	Run created and queued.
400	Invalid request. workflow_id is missing or inputs is not an object.
401	Missing or invalid Bearer token. See Authentication.
403	Invalid API token context. The token does not have access to the requested workspace.
409	Idempotency key conflict. The same key was used with a different workflowId.
429	Rate limit reached. Either the daily run limit or concurrent run limit has been exceeded.
500	Internal server error.

Run lifecycle

After creation, a run progresses through these statuses:

1. QUEUED — The run is waiting to be picked up.
2. STARTING — The run is initializing (creating workspace, starting execution).
3. RUNNING — The workflow is actively executing.
4. COMPLETED — The workflow finished. Output is available via Get Run Status.
5. FAILED — The workflow encountered an error. Check the error field for details.
6. CANCELED — The run was canceled while queued.

You can only cancel a run while the status is QUEUED. Once a run moves to STARTING or later, cancellation is not possible.

What’s next

• Get Run Status — Poll for run progress and results.
• Cancel Queued Run — Cancel a run before execution starts.
• Authentication — Create and manage API tokens.