# Get Catalog Measurements

Source: https://recoupable.dev/docs/api-reference/songs/catalog-measurements

Get the latest play counts and a derived valuation band for a catalog. Measurements are captured by [Create measurement job](/api-reference/research/measurement-jobs) runs; the band is computed at read time from the latest capture per song.

## GET /api/catalogs/{catalogId}/measurements

Full OpenAPI specification: https://recoupable.dev/docs/spec/releases.json

## Authentication

This operation requires one of the security alternatives in the specification below. Security scheme definitions are included where present in the published specification.

[Authentication guide](https://recoupable.dev/docs/authentication)

## Operation and referenced schemas

```json
{
  "openapi": "3.1.0",
  "info": {
    "title": "Recoup API - Releases",
    "description": "API documentation for the Recoup platform - an AI agent platform for the music industry",
    "license": {
      "name": "MIT"
    },
    "version": "1.0.0"
  },
  "servers": [
    {
      "url": "https://api.recoupable.dev"
    }
  ],
  "paths": {
    "/api/catalogs/{catalogId}/measurements": {
      "get": {
        "description": "Get the latest play counts and a derived valuation band for a catalog. Measurements are captured by [Create measurement job](/api-reference/research/measurement-jobs) runs; the band is computed at read time from the latest capture per song.",
        "security": [
          {
            "apiKeyAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "catalogId",
            "in": "path",
            "description": "The unique identifier of the catalog to read measurements for. The catalog must belong to the authenticated account. Malformed (non-uuid) values are rejected with 400.",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "account_id",
            "in": "query",
            "description": "Act on behalf of this account (UUID). Only applicable when the authenticated account has access to the target account, for example an organization key acting for a member account. The catalog ownership check then runs against this account instead of the caller. Omitted: the caller's own account.",
            "required": false,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "artist_account_id",
            "in": "query",
            "description": "Optional artist account to scope the read to. When present, measurements and the valuation band cover only the catalog's songs linked to this artist account (via song_artists); when absent, the whole catalog. A song linked to multiple artists counts for each of them. An artist with no linked measured songs in the catalog yields measured_song_count 0 and an empty measurements array. Malformed (non-uuid) values are rejected with 400.",
            "required": false,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "page",
            "in": "query",
            "description": "Page number of the measurements array (default 1). Pagination only windows the measurements rows - the aggregates always cover the entire scope. Invalid values are rejected with 400.",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "default": 1
            }
          },
          {
            "name": "limit",
            "in": "query",
            "description": "Number of measurement rows per page (default 50, max 100). Invalid values are rejected with 400.",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 50
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Latest per-song measurements and the derived valuation band",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CatalogMeasurementsResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad request - malformed catalogId or artist_account_id, or invalid page/limit",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CatalogSongsErrorResponse"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized - missing or invalid credentials",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CatalogSongsErrorResponse"
                }
              }
            }
          },
          "404": {
            "description": "Not found - the catalog does not exist or belongs to a different account",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CatalogSongsErrorResponse"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "CatalogMeasurementsResponse": {
        "type": "object",
        "description": "Latest per-song play counts for a catalog plus the valuation band derived from them",
        "properties": {
          "status": {
            "type": "string",
            "enum": [
              "success",
              "error"
            ],
            "description": "Status of the request"
          },
          "measurements": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/CatalogTrackMeasurement"
            },
            "description": "One page of latest-per-ISRC measurements (the requested page/limit window), sorted by play count descending. One entry per measured song: the newest capture per ISRC; songs never measured are omitted. Use measured_song_count / pagination for the size of the full set - the aggregates are NOT limited to this page."
          },
          "pagination": {
            "$ref": "#/components/schemas/CatalogMeasurementsPagination"
          },
          "measured_song_count": {
            "type": "integer",
            "description": "Total number of measured songs in scope (the whole catalog, or the artist subset when filtered), computed over the entire scope regardless of pagination - no row cap"
          },
          "valuation": {
            "$ref": "#/components/schemas/ValuationBand"
          },
          "total_streams": {
            "type": "integer",
            "description": "Sum of the latest play counts across ALL measured songs in scope, computed in a single SQL aggregate regardless of pagination - no row cap"
          },
          "artist_account_id": {
            "type": "string",
            "format": "uuid",
            "nullable": true,
            "description": "Echoes the applied artist_account_id filter: the uuid when the response was scoped to that artist, null when the response covers the whole catalog. Clients that request an artist scope should verify this echo before treating the numbers as artist-scoped."
          },
          "catalog_age_years": {
            "type": "integer",
            "description": "Catalog age in years used for the annual run-rate: from the earliest Spotify release date of the source run's albums, minimum 1; defaults to 5 when no release date is resolvable."
          },
          "error": {
            "type": "string",
            "description": "Error message (only present if status is 'error')"
          }
        }
      },
      "CatalogSongsErrorResponse": {
        "type": "object",
        "properties": {
          "status": {
            "type": "string",
            "enum": [
              "error"
            ],
            "description": "Status of the request"
          },
          "error": {
            "type": "string",
            "description": "Error message describing what went wrong"
          }
        }
      },
      "CatalogTrackMeasurement": {
        "type": "object",
        "description": "The most recent Spotify play-count measurement for one song (ISRC) in the catalog",
        "properties": {
          "isrc": {
            "type": "string",
            "description": "ISRC of the song"
          },
          "title": {
            "type": "string",
            "nullable": true,
            "description": "Song title, when known"
          },
          "playcount": {
            "type": "integer",
            "description": "Latest Spotify platform-displayed play count"
          },
          "measured_at": {
            "type": "string",
            "format": "date-time",
            "description": "ISO timestamp of when the play count was captured"
          }
        }
      },
      "CatalogMeasurementsPagination": {
        "type": "object",
        "description": "Pagination metadata for the measurements array - the same envelope as catalog songs",
        "properties": {
          "total_count": {
            "type": "integer",
            "description": "Total number of measured songs in scope (equals measured_song_count)"
          },
          "page": {
            "type": "integer",
            "description": "Current page number"
          },
          "limit": {
            "type": "integer",
            "description": "Number of measurement rows per page"
          },
          "total_pages": {
            "type": "integer",
            "description": "Total number of pages available"
          }
        }
      },
      "ValuationBand": {
        "type": "object",
        "description": "Estimated catalog value in USD, derived at read time from the latest measurements - the same model as the recoupable.dev valuation card. Annual run-rate = lifetime streams / catalog age (lifetime-average proxy), converted to net label share (all-DSP gross-up 1.25/1.4/1.6, 15% distribution fee, 25% royalty share, $0.0035 per Spotify stream) and multiplied by a 10x/13x/16x master-catalog market multiple.",
        "properties": {
          "low": {
            "type": "number",
            "description": "Low estimate in USD (1.25x gross-up, 10x multiple)"
          },
          "mid": {
            "type": "number",
            "description": "Central estimate in USD (1.4x gross-up, 13x multiple)"
          },
          "high": {
            "type": "number",
            "description": "High estimate in USD (1.6x gross-up, 16x multiple)"
          }
        }
      }
    },
    "securitySchemes": {
      "apiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "x-api-key",
        "description": "Your Recoup API key. [Learn more](/quickstart#api-keys)."
      },
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer"
      }
    }
  }
}
```