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.

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