Dynamiq
Runs

Create a run

Starts a run of the deployed app. Three execution modes are supported: **synchronous** (default — the request blocks until the run reaches a terminal state and returns the final run), **background** (`background: true` — returns `202 Accepted` immediately with the created run), and **streaming** (`stream: true` — the response is a Server-Sent Events stream of run events). `stream` and `background` cannot both be true. Files can be attached either by referencing previously uploaded files via `file_ids` or by sending the request as `multipart/form-data` with one or more `files` parts (max 128 MiB).

POST
/v1/runs

Authorization

accessKey
AuthorizationBearer <token>

Organization or project Access Key created in the Dynamiq console. Used for deployed-app (Runs API), AI Gateway, traces collector, and management API requests. Send as Authorization: Bearer <access-key>.

In: header

Request Body

TypeScript Definitions

Use the request body type in TypeScript.

JSON body for POST /v1/runs.

Response Body

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/v1/runs" \  -H "Content-Type: application/json" \  -d '{    "input": {      "ticket_subject": "Charged twice for June invoice",      "ticket_body": "Hi, my card was charged twice this month. Order #4812."    },    "user_id": "customer-7421",    "session_id": "3d3e8a1f-09a6-4f64-9d68-1d2f3a4b5c6d"  }'
{
  "data": {
    "id": "8c2c8e2e-2f0a-4f4e-9f4f-6e1a52f0a001",
    "app_id": "4f6e1c2a-7b8d-4e9f-a1b2-c3d4e5f60718",
    "status": "completed",
    "started_at": "2026-06-10T09:15:21Z",
    "ended_at": "2026-06-10T09:15:34Z",
    "input": {
      "ticket_subject": "Charged twice for June invoice"
    },
    "output": {
      "category": "billing",
      "priority": "high",
      "suggested_reply": "Hi! Sorry about the duplicate charge..."
    },
    "user_id": "customer-7421",
    "session_id": "3d3e8a1f-09a6-4f64-9d68-1d2f3a4b5c6d"
  }
}
{
  "data": {
    "id": "8c2c8e2e-2f0a-4f4e-9f4f-6e1a52f0a001",
    "app_id": "4f6e1c2a-7b8d-4e9f-a1b2-c3d4e5f60718",
    "status": "created",
    "started_at": "2026-06-10T09:15:21Z",
    "input": {
      "ticket_subject": "App crashes when exporting report"
    }
  }
}
{
  "error": {
    "code": "bad_request",
    "message": "Bad Request",
    "details": {
      "input": "cannot be blank"
    }
  }
}
{
  "error": {
    "code": "unauthorized",
    "message": "Unauthorized"
  }
}
{
  "error": {
    "code": "not_found",
    "message": "Not Found"
  }
}

List runs

Lists runs of the app, most recently started first by default. Runs with at least one unresolved human-feedback or approval request are reported with the synthetic `awaiting_input` status.

Get a run

Returns a single run. If the run has unresolved human-feedback or approval requests, its status is reported as `awaiting_input` and the pending requests are listed in `input_requests`.