API REFERENCE

Get Chat Run Status

On this page

GET/api/chat/runs/{runId}

Status of an asynchronous run started via POST /api/chat/runs. Returns a point-in-time snapshot (is it done?) — not the generated content.

Related endpoints - POST /api/chat/runs — starts the run this reports on. - GET /api/chat/{chatId}/stream — read the content: poll this to know whether a run finished; use the stream to watch the output as it's produced. - POST /api/chat — the interactive, streaming counterpart to a headless run.

Authentication

x-api-key in header

Request

cURL

curl --request GET \
  --url 'https://api.recoupable.dev/api/chat/runs/YOUR_RUN_ID' \
  --header 'x-api-key: YOUR_API_KEY'

Replace the YOUR_ placeholders with your values. Required query parameters are included; optional parameters are listed below.

Parameters

Path parameters

runIdstringrequired

The durable workflow run id returned by POST /api/chat/runs.

Responses

200Run status snapshot

application/json

runIdstringrequired

The durable workflow run id.

statusstring · enumrequired

Lifecycle state of the run. Read the produced content via the chat (chatId from the start response).

Values: "queued", "running", "completed", "failed", "cancelled"

createdAtstring

When the workflow run was created.

format: date-time

startedAtstringnullable

When the workflow run started executing; null while queued.

format: date-time

completedAtstringnullable

When the workflow run reached a terminal state; null while queued or running.

format: date-time

durationMsintegernullable

completedAt - startedAt in milliseconds; null until the run is terminal.

404No run found for the given runId

application/json

statusstring · enumrequired

Status of the request

Values: "error"

messagestringrequired

Error message describing what went wrong

Full specification

Download the OpenAPI file for complete schemas, constraints, and examples.

Download research.json

View operation source

json

{
  "description": "Status of an asynchronous run started via [`POST /api/chat/runs`](/api-reference/chat/runs). Returns a point-in-time snapshot (**is it done?**) — not the generated content.\n\n**Related endpoints**\n- [`POST /api/chat/runs`](/api-reference/chat/runs) — starts the run this reports on.\n- [`GET /api/chat/{chatId}/stream`](/api-reference/chat/workflow-stream) — read the **content**: poll *this* to know **whether** a run finished; use the stream to **watch the output** as it's produced.\n- [`POST /api/chat`](/api-reference/chat/workflow) — the interactive, streaming counterpart to a headless run.",
  "security": [
    {
      "apiKeyAuth": []
    }
  ],
  "parameters": [
    {
      "name": "runId",
      "in": "path",
      "required": true,
      "description": "The durable workflow run id returned by [POST /api/chat/runs](/api-reference/chat/runs).",
      "schema": {
        "type": "string"
      },
      "example": "wrun_01KVWZNM82NA7XKNEWWHG8VPHJ"
    }
  ],
  "responses": {
    "200": {
      "description": "Run status snapshot",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ChatRunStatusResponse"
          }
        }
      }
    },
    "404": {
      "description": "No run found for the given runId",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ChatGenerateErrorResponse"
          }
        }
      }
    }
  }
}