API REFERENCE

Get Runs

On this page

GET/api/runs

Get background runs, newest first. A run is the generic status resource for long-running work. kind selects the run type (valuation and music today); future kinds are new enum values here, never new endpoints.

Authentication

x-api-key in header

bearerAuth bearer

Request

cURL

curl --request GET \
  --url 'https://api.recoupable.dev/api/runs?kind=YOUR_KIND' \
  --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.

kindquery · stringrequired

limitquery · integer

cURL for this request

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

Parameters

Query parameters

kindstring · enumrequired

Required. The run type to list. Unknown kinds are rejected with 400.

Values: "valuation", "music"

limitinteger

Optional. Maximum runs to return, newest first. Defaults to 1 (the latest run).

Default: 1

Responses

200The calling account's runs of the requested kind, newest first. Empty when the account has never run one.

application/json

statusstring · enum

Status of the request

Values: "success", "error"

runsarray<one of>

Runs, newest first. Empty when the account has never run one of this kind. The item shape follows the requested kind.

Item properties

oneOf · ValuationRun 1

One background run. id is opaque; state is a domain phase, not a storage value: queued (capture accepted, not yet scraping), measuring (capture in flight, or finished moments ago and being claimed), claimed (catalog materialized - result.catalog_id is set), failed (the capture finished but no catalog was claimed, or the capture itself failed).

idstring

Opaque run id. Do not infer anything from its format; it is stable for polling a single run across requests.

format: uuid

kindstring · enum

The run type.

Values: "valuation"

statestring · enum

Domain phase of the run.

Values: "queued", "measuring", "claimed", "failed"

album_countinteger

Number of releases in the run's capture scope.

created_atstring

When the run was created.

format: date-time

resultobjectnullable

Set once the run is claimed; null before that.

Properties

catalog_idstring

The materialized catalog. Read its value band via Get Catalog Measurements.

format: uuid

oneOf · MusicRun 2

One music generation, surfaced as a run. id is the generation's id: read the full record, including its logs, with Get Music Generation.

idstring

The generation's id.

format: uuid

kindstring · enum

The run type.

Values: "music"

statestring · enum

Domain phase of the run: queued before the workflow picks it up, generating while the model renders, then complete or failed.

Values: "queued", "generating", "complete", "failed"

created_atstring

When the generation was created.

format: date-time

resultobjectnullable

Set once the generation completes; null before that.

Properties

generation_idstring

The completed generation.

format: uuid

audio_urlstring

Playable audio URL.

errorstring

Error message (only present if status is 'error')

400Missing or unknown kind, or invalid limit.

application/json

statusstring · enum

Status of the request

Values: "error"

errorstring

Error message describing what went wrong

401Missing or invalid credentials.

application/json

statusstring · enum

Status of the request

Values: "error"

errorstring

Error message describing what went wrong

Full specification

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

Download releases.json

View operation source

json

{
  "summary": "Get runs",
  "description": "Get background runs, newest first. A run is the generic status resource for long-running work. `kind` selects the run type (`valuation` and `music` today); future kinds are new enum values here, never new endpoints.",
  "security": [
    {
      "apiKeyAuth": []
    },
    {
      "bearerAuth": []
    }
  ],
  "parameters": [
    {
      "name": "kind",
      "in": "query",
      "required": true,
      "schema": {
        "type": "string",
        "enum": [
          "valuation",
          "music"
        ]
      },
      "description": "Required. The run type to list. Unknown kinds are rejected with 400."
    },
    {
      "name": "limit",
      "in": "query",
      "required": false,
      "schema": {
        "type": "integer",
        "minimum": 1,
        "maximum": 20,
        "default": 1
      },
      "description": "Optional. Maximum runs to return, newest first. Defaults to 1 (the latest run)."
    }
  ],
  "responses": {
    "200": {
      "description": "The calling account's runs of the requested kind, newest first. Empty when the account has never run one.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/GetRunsResponse"
          }
        }
      }
    },
    "400": {
      "description": "Missing or unknown kind, or invalid limit.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/CatalogSongsErrorResponse"
          }
        }
      }
    },
    "401": {
      "description": "Missing or invalid credentials.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/CatalogSongsErrorResponse"
          }
        }
      }
    }
  }
}