Dynamiq
Runs

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
/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

Query Parameters

status?array<>

Filter by run status. Repeat the parameter to filter by several statuses. awaiting_input is a synthetic status matching paused/started runs that have an unresolved input request.

user_id?string

Filter by the caller-supplied user identifier.

session_id?string

Filter by session UUID.

page?integer

Page number (1-based).

page_size?integer

Number of items per page.

sort?string

Comma-separated sort fields. Prefix a field with - for descending order, e.g. sort=-started_at.

Response Body

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/v1/runs"
{
  "data": [
    {
      "id": "8c2c8e2e-2f0a-4f4e-9f4f-6e1a52f0a001",
      "status": "completed",
      "started_at": "2026-06-10T09:15:21Z",
      "ended_at": "2026-06-10T09:15:34Z",
      "input": {
        "ticket_subject": "Charged twice for June invoice",
        "ticket_body": "Hi, my card was charged twice this month..."
      },
      "output": {
        "category": "billing",
        "priority": "high",
        "suggested_reply": "Hi! Sorry about the duplicate charge..."
      },
      "user_id": "customer-7421",
      "session_id": "3d3e8a1f-09a6-4f64-9d68-1d2f3a4b5c6d"
    }
  ],
  "pagination": {
    "page": 1,
    "page_size": 25,
    "page_count": 1,
    "total_count": 1
  }
}
{
  "error": {
    "code": "bad_request",
    "message": "Bad Request",
    "details": {
      "input": "cannot be blank"
    }
  }
}
{
  "error": {
    "code": "unauthorized",
    "message": "Unauthorized"
  }
}
{
  "error": {
    "code": "not_found",
    "message": "Not Found"
  }
}

Upload a file

Uploads a file to the app's storage so it can later be attached to a run via `file_ids`. The maximum request size is 128 MiB.

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).