Get Catalog Measurements

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