Recoup

Get started with Recoup.

Try Our Platform

Use Recoup’s AI tools for your artists, releases, and catalog.

Build Your Platform

Our team builds custom AI software for your business.

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.

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

cURL for this request
curl --request GET \
  --url 'https://api.recoupable.dev/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.

Example: "wrun_01KVWZNM82NA7XKNEWWHG8VPHJ"

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

When the workflow run was created; null if unavailable, including for terminal runs.

Example: "2026-08-25T19:33:56.000Z"

format: date-time

startedAtstring | null

When execution started; null while unavailable or if its timing getter fails, including for terminal runs.

Example: "2026-08-25T19:34:16.386Z"

format: date-time

completedAtstring | null

When the run reached a terminal state; null while unavailable or if its timing getter fails, including for terminal runs.

Example: "2026-08-25T20:15:55.000Z"

format: date-time

durationMsinteger | null

completedAt minus startedAt in milliseconds; null if either timestamp is unavailable, including for terminal runs.

Example: 2498614

404Run not found

application/json

statusstring · enumrequired

Values: "error"

errorstringrequired

Example: "Run not found"

Full specification

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

Download research.json
View operation source
json
{
  "operationId": "getChatRunsByRunId",
  "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": "Run not found",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ChatRunNotFoundError"
          }
        }
      }
    }
  }
}