---
title: "Create run"
method: POST
path: "/runs"
tags: ["Runs"]
---

# Create run

`POST /runs`

## Request

- Base URL: `https://api.edgaze.ai/v1`
- URL: `https://api.edgaze.ai/v1/runs`
- Auth: HTTP bearer

Start an asynchronous workflow run. Returns 202 with URLs to poll status, read events, and stream progress.

## Headers

- `Idempotency-Key` string

## Request body

- CreateRunRequest: Request body for POST /runs.
  - `workflow` string, uuid: Workflow UUID to run.
  - `workflowId` string, uuid: Deprecated compatibility alias for `workflow`. Prefer `workflow`. When both are set, `workflow` wins.
  - `inputs` object: Map of exact input `nodeId` (preferred) or `name` to value, using the keys from the workflow's `inputSchema`. Unknown or ambiguous keys are rejected with 400 `invalid_inputs`. Omit entirely for a workflow that takes no inputs.
  - `idempotencyKey` string: Currently optional for backward compatibility, but strongly recommended for every request. Account-scoped and case-sensitive (max 255 chars). Prefer the `Idempotency-Key` header; when both are set they must match. The fingerprint covers workflow, normalized inputs, and requested version.
  - `version` string, uuid: Optional immutable workflow version to run. When omitted, resolves to the caller's pinned version, or the workflow's active version when there is no pin.

## Response `202`

Run accepted.

- CreateRunResponse: Response body for POST /runs (202 Accepted).
  - `run` AcceptedRun, required: The `run` sub-object returned by POST /runs (202 Accepted).
    - `id` string, uuid, required: Run UUID. Use it for every follow-up run call.
    - `status` 'accepted', required: Always the constant `accepted`. This is an acknowledgement that the run was durably enqueued, not a lifecycle status: it is deliberately NOT a `PublicRunStatus` value, because no execution has happened yet. Read GET /runs/{id} for the real status.
    - `statusUrl` string, uri, required: Absolute URL for GET /runs/{id}.
    - `eventsUrl` string, uri, required: Absolute URL for GET /runs/{id}/events.
    - `streamUrl` string, uri, required: Absolute URL for the SSE stream.

## Other responses

- `400`: Request rejected before the run started. `invalid_json`: the body was not parseable JSON. `missing_workflow`: no `workflow` id was supplied. `invalid_inputs`: one or more inputs were rejected — `error.details` lists the offending `input` keys. `invalid_request`: the `Idempotency-Key` header conflicted with `body.idempotencyKey`.
- `401`: Invalid or missing API key.
- `402`: This API key has reached its spend cap.
- `403`: Not entitled to run this workflow (`forbidden`), the account is restricted (`account_restricted`), or the creator's paid listings are paused (`creator_listings_paused`).
- `404`: Workflow not found.
- `409`: Idempotency key reused with a different request (`idempotency_conflict`), or the workflow needs third-party accounts the caller has not connected (`integration_connection_required`; `error.details` lists them, each with a `connectUrl`).
- `429`: Rate limited (60 POST /runs per minute per API key).
- `500`: Unexpected server error.

---

[API](https://skmtc.dev/edgaze/apis/edgaze-api.md) · [All operations](https://skmtc.dev/edgaze/apis/edgaze-api/llms.txt) · [OpenAPI document](https://skmtc.dev/edgaze/apis/edgaze-api/revisions/cfc6436d2f90?raw)