---
title: Create Run
description: Start an asynchronous workflow run. Returns 202 Accepted with a run id and polling URLs.
source: https://www.edgaze.ai/docs/api/create-run
section: api
---
# Create Run

> Start an asynchronous workflow run. Returns 202 Accepted with a run id and polling URLs.

```apibar
create-run
```

## Overview

This is the primary execution endpoint. It accepts a workflow id and an inputs object, validates entitlement and spend caps synchronously, then returns **202 Accepted** with a run id and URLs for polling.

Runs are asynchronous. A successful response means the run was queued, not finished. Always follow `statusUrl` until the run reaches a terminal state, then read outputs from the same response or from GET /runs/{id}/events for step-level progress.

```doccallout
{"variant":"info","text":"POST immediately after resolving inputSchema from GET /workflows/{id}. Store run.id and poll every 1-3 seconds. Handle 402 spend_cap_reached and 429 rate_limited at request time; handle wallet failures by polling for status failed."}
```

## Authorization

Requires `run:execute`.

```apiscopes
create-run
```

## Parameters

```apiparams
create-run
```

## Response

Only POST /runs is rate-limited (60 req/min per key). Invalid JSON returns 400 `invalid_json`. Missing workflow returns 400 `missing_workflow`.

Example payloads are in the request/response panel above.

## Edge cases

```apiedges
create-run
```

---

## Endpoint reference
- **Method:** `POST`
- **Path:** `https://api.edgaze.ai/v1/runs`
- **Scopes:** `run:execute`
## Parameters
| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `Authorization` | header | string | yes | Bearer token with run:execute scope. |
| `workflow` | body | string | yes | Workflow UUID. Alias: workflowId. |
| `inputs` | body | object | yes | Map of input field names (or nodeIds) to values matching the workflow inputSchema. |
| `idempotencyKey` | body | string | no | Optional idempotency key to safely retry run creation. |
## Example responses

### 202 Accepted

Run accepted. Poll statusUrl until terminal state.

```json
{
  "run": {
    "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
    "status": "accepted",
    "accessToken": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "statusUrl": "https://api.edgaze.ai/v1/runs/7c9e6679-7425-40de-944b-e07fc1f90ae7",
    "eventsUrl": "https://api.edgaze.ai/v1/runs/7c9e6679-7425-40de-944b-e07fc1f90ae7/events",
    "streamUrl": "https://api.edgaze.ai/v1/runs/7c9e6679-7425-40de-944b-e07fc1f90ae7/stream"
  }
}
```

### 402 Spend cap reached
```json
{
  "error": {
    "code": "spend_cap_reached",
    "message": "This API key has reached its spend cap. Raise the cap or wait for the window to reset."
  }
}
```

### 403 Forbidden
```json
{
  "error": {
    "code": "forbidden",
    "message": "You do not have access to run this workflow."
  }
}
```

### 429 Rate limited

60 requests per minute per API key.

```json
{
  "error": {
    "code": "rate_limited",
    "message": "Rate limit exceeded. Try again later."
  }
}
```

## Edge cases

### Async wallet failures (HTTP 202)

POST returns 202 before wallet funding is verified. If balance is insufficient, the run fails asynchronously. Poll GET /runs/{id} and check for status failed.

### Spend cap is synchronous (HTTP 402 · `spend_cap_reached`)

Spend cap checks happen before the run row is created. A cap breach returns 402 immediately with no run ID.

### Rate limit ordering (HTTP 429 · `rate_limited`)

Rate limiting is enforced before run execution. A 429 never creates a partial run.

### Same billing as the product UI

API runs use identical entitlement, wallet, bundle, and BYOK billing paths as runs started from the web app.

## Notes

- Only POST /runs is rate-limited (60 req/min per key).
- Invalid JSON returns 400 invalid_json. Missing workflow returns 400 missing_workflow.