API REFERENCE

Get Catalog Valuations

On this page

GET/api/catalogs/{catalogId}/valuations

Get the persisted valuation history for a catalog, latest first. A row is written each time a valuation band is computed for the whole catalog (valuation runs and measurement reads persist at most one row per catalog per day). Use limit=1 for the current value. History is what makes week-over-week deltas possible.

Authentication

x-api-key in header

bearerAuth bearer

Request

cURL

curl --request GET \
  --url 'https://api.recoupable.dev/api/catalogs/YOUR_CATALOG_ID/valuations' \
  --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

catalogIdstringrequired

The unique identifier of the catalog. The catalog must belong to the authenticated account. Malformed (non-uuid) values are rejected with 400.

Query parameters

limitinteger

Maximum number of valuation rows to return, latest first (default 30, max 100). limit=1 returns the current value. Invalid values are rejected with 400.

Default: 30

Responses

200The catalog's persisted valuation rows, latest first. Empty when no valuation has been persisted yet.

application/json

statusstringrequired

valuationsarray<object>required

Persisted valuation rows, latest first.

Item properties

lownumberrequired

Low end of the estimated catalog value band, USD.

midnumberrequired

Midpoint of the estimated catalog value band, USD.

highnumberrequired

High end of the estimated catalog value band, USD.

measured_song_countintegerrequired

Songs measured in the capture this valuation was computed from.

total_streamsintegerrequired

Whole-catalog lifetime stream total at measurement time.

measured_atstringrequired

When the underlying measurement was taken.

format: date-time

400Malformed catalogId or limit

application/json

errorintegerrequired

format: int32

messagestringrequired

401Missing or invalid credentials

application/json

errorintegerrequired

format: int32

messagestringrequired

404Catalog not found or not owned by the authenticated account

application/json

errorintegerrequired

format: int32

messagestringrequired

Full specification

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

Download releases.json

View operation source

json

{
  "description": "Get the persisted valuation history for a catalog, latest first. A row is written each time a valuation band is computed for the whole catalog (valuation runs and measurement reads persist at most one row per catalog per day). Use limit=1 for the current value. History is what makes week-over-week deltas possible.",
  "security": [
    {
      "apiKeyAuth": []
    },
    {
      "bearerAuth": []
    }
  ],
  "parameters": [
    {
      "name": "catalogId",
      "in": "path",
      "description": "The unique identifier of the catalog. The catalog must belong to the authenticated account. Malformed (non-uuid) values are rejected with 400.",
      "required": true,
      "schema": {
        "type": "string",
        "format": "uuid"
      }
    },
    {
      "name": "limit",
      "in": "query",
      "description": "Maximum number of valuation rows to return, latest first (default 30, max 100). limit=1 returns the current value. Invalid values are rejected with 400.",
      "required": false,
      "schema": {
        "type": "integer",
        "minimum": 1,
        "maximum": 100,
        "default": 30
      }
    }
  ],
  "responses": {
    "200": {
      "description": "The catalog's persisted valuation rows, latest first. Empty when no valuation has been persisted yet.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/CatalogValuationsResponse"
          }
        }
      }
    },
    "400": {
      "description": "Malformed catalogId or limit",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "401": {
      "description": "Missing or invalid credentials",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "404": {
      "description": "Catalog not found or not owned by the authenticated account",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    }
  }
}