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.

Try it

Fill in the fields, send the request from your browser, and read the live response. The curl below updates as you type.

API keyx-api-key header

Kept in this browser tab only and cleared when it closes.

runIdpath · stringrequired

cURL for this request

curl --request GET \
  --url 'https://recoup-api.vercel.app/api/chat/runs/{runId}'

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"
          }
        }
      }
    }
  }
}