Recoup

Get started with Recoup.

Try Our Platform

Use Recoup’s AI tools for your artists, releases, and catalog.

Build Your Platform

Our team builds custom AI software for your business.

API REFERENCE

Daily Catalog Streams

On this page
GET/api/catalogs/{catalogId}/streams

Saved Luminate worldwide aggregate calendar-day streams across reporting DSPs, not Spotify-only or royalty statements. Includes current catalog recordings even when unmeasured, latest collection status, per-recording daily rows/retrieval time, missing dates, equal-period totals and growth. Newer source corrections win; historical versions remain stored. Missing days and changed provider recording identity suppress comparisons. Zero baseline yields null percentage. Page through pagination.has_more; summary_scope is page. Reads make no provider requests. Standard MCP: get_catalog_streams. Requires API and database feature release; unavailable to delegated OAuth. Unchanged daily values reuse their saved versions; new dates and corrections are appended, with fresh coverage/provenance receipts for every run.

Authentication

x-api-key in header

bearerAuth bearer

Request

cURL
curl --request GET \
  --url 'https://api.recoupable.dev/api/catalogs/YOUR_CATALOG_ID/streams?since=YOUR_SINCE&days=YOUR_DAYS' \
  --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.

Kept in this browser tab only and cleared when it closes.

cURL for this request
curl --request GET \
  --url 'https://recoup-api.vercel.app/api/catalogs/{catalogId}/streams'

Parameters

Path parameters

catalogIdstringrequired

Catalog owned by the authenticated account or an organization it currently belongs to.

Query parameters

sincestringrequired

Current period start, inclusive. Previous period has the same length and immediately precedes it.

daysintegerrequired

Equal period length; end dates are exclusive. Missing days suppress growth.

pageinteger

Default: 1

limitinteger

Default: 25

Responses

200Saved history and comparisons

application/json

statusstring
catalog_idstring

format: uuid

providerstring · enum

Values: "luminate"

platformstring · enum

Values: "all_dsps"

metricstring · enum

Values: "daily_streams"

latest_runobject | null

Run status, per-ISRC coverage, errors, window and completion timestamp.

Properties for latest_run
idstring

format: uuid

catalog_idstring

format: uuid

revisionstring

format: uuid

scheduled_daystring

format: date

sincestring

format: date

untilstring

format: date

statusstring · enum

Values: "queued", "running", "complete", "partial", "failed", "cancelled"

coverageobject
errorstring | null
created_atstring

format: date-time

finished_atstring | null

format: date-time

territorystring · enum

Values: "worldwide"

semanticsstring
source_updated_atnull
periodsobject
Properties for periods
previousobject
Properties for previous
startstring

format: date

end_exclusivestring

format: date

currentobject
Properties for current
startstring

format: date

end_exclusivestring

format: date

daysinteger
timezonestring · enum

Values: "UTC"

paginationobject
Properties for pagination
pageinteger
limitinteger
total_countinteger
has_moreboolean
summary_scopestring · enum

Values: "page"

recordingsarray<object>
Item properties for recordings
isrcstring
namestring | null
provider_recording_idstring | null
retrieved_atstring | null

format: date-time

daysarray<object>
Item properties for days
datestringrequired

format: date

streamsinteger | nullrequired
statestring · enum

Values: "comparable", "incomplete", "unfinished_period", "invalid_observation"

missing_daysarray<string>
Item properties for missing_days

string

previous_streamsinteger | null
current_streamsinteger | null
absolute_growthinteger | null
percentage_growthnumber | null
zero_baselineboolean
latest_attemptobject | null

Fresh recording-level receipt for the latest run, including state, observed_days, retrieved_at, source_hash and provider_recording_id. Observation retrieved_at is when its retained version was introduced.

Properties for latest_attempt
statestring · enum

Values: "complete", "partial", "unavailable", "failed"

observed_daysinteger

minimum: 0 · maximum: 62

retrieved_atstring | null

format: date-time

source_hashstring | null
provider_recording_idstring | null
400Invalid input or incomplete calendar period

No response body schema is specified.

401Authentication required

No response body schema is specified.

404Catalog not accessible

No response body schema is specified.

503Storage, configuration or dispatch unavailable

No response body schema is specified.

Full specification

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

Download releases.json
View operation source
json
{
  "summary": "Read daily catalog streams",
  "description": "Saved Luminate worldwide aggregate calendar-day streams across reporting DSPs, not Spotify-only or royalty statements. Includes current catalog recordings even when unmeasured, latest collection status, per-recording daily rows/retrieval time, missing dates, equal-period totals and growth. Newer source corrections win; historical versions remain stored. Missing days and changed provider recording identity suppress comparisons. Zero baseline yields null percentage. Page through pagination.has_more; summary_scope is page. Reads make no provider requests. Standard MCP: get_catalog_streams. Requires API and database feature release; unavailable to delegated OAuth. Unchanged daily values reuse their saved versions; new dates and corrections are appended, with fresh coverage/provenance receipts for every run.",
  "security": [
    {
      "apiKeyAuth": []
    },
    {
      "bearerAuth": []
    }
  ],
  "parameters": [
    {
      "name": "catalogId",
      "in": "path",
      "required": true,
      "schema": {
        "type": "string",
        "format": "uuid"
      },
      "description": "Catalog owned by the authenticated account or an organization it currently belongs to."
    },
    {
      "name": "since",
      "in": "query",
      "required": true,
      "schema": {
        "type": "string",
        "format": "date"
      },
      "description": "Current period start, inclusive. Previous period has the same length and immediately precedes it."
    },
    {
      "name": "days",
      "in": "query",
      "required": true,
      "schema": {
        "type": "integer",
        "minimum": 1,
        "maximum": 31
      },
      "description": "Equal period length; end dates are exclusive. Missing days suppress growth."
    },
    {
      "name": "page",
      "in": "query",
      "schema": {
        "type": "integer",
        "minimum": 1,
        "maximum": 1000000,
        "default": 1
      }
    },
    {
      "name": "limit",
      "in": "query",
      "schema": {
        "type": "integer",
        "minimum": 1,
        "maximum": 25,
        "default": 25
      }
    }
  ],
  "responses": {
    "200": {
      "description": "Saved history and comparisons",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "status": {
                "type": "string"
              },
              "catalog_id": {
                "type": "string",
                "format": "uuid"
              },
              "provider": {
                "type": "string",
                "enum": [
                  "luminate"
                ]
              },
              "platform": {
                "type": "string",
                "enum": [
                  "all_dsps"
                ]
              },
              "metric": {
                "type": "string",
                "enum": [
                  "daily_streams"
                ]
              },
              "latest_run": {
                "$ref": "#/components/schemas/CatalogStreamRun",
                "description": "Run status, per-ISRC coverage, errors, window and completion timestamp."
              },
              "territory": {
                "type": "string",
                "enum": [
                  "worldwide"
                ]
              },
              "semantics": {
                "type": "string"
              },
              "source_updated_at": {
                "type": "null"
              },
              "periods": {
                "type": "object",
                "properties": {
                  "previous": {
                    "type": "object",
                    "properties": {
                      "start": {
                        "type": "string",
                        "format": "date"
                      },
                      "end_exclusive": {
                        "type": "string",
                        "format": "date"
                      }
                    }
                  },
                  "current": {
                    "type": "object",
                    "properties": {
                      "start": {
                        "type": "string",
                        "format": "date"
                      },
                      "end_exclusive": {
                        "type": "string",
                        "format": "date"
                      }
                    }
                  },
                  "days": {
                    "type": "integer"
                  },
                  "timezone": {
                    "type": "string",
                    "enum": [
                      "UTC"
                    ]
                  }
                }
              },
              "pagination": {
                "type": "object",
                "properties": {
                  "page": {
                    "type": "integer"
                  },
                  "limit": {
                    "type": "integer"
                  },
                  "total_count": {
                    "type": "integer"
                  },
                  "has_more": {
                    "type": "boolean"
                  }
                }
              },
              "summary_scope": {
                "type": "string",
                "enum": [
                  "page"
                ]
              },
              "recordings": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "isrc": {
                      "type": "string"
                    },
                    "name": {
                      "type": [
                        "string",
                        "null"
                      ]
                    },
                    "provider_recording_id": {
                      "type": [
                        "string",
                        "null"
                      ]
                    },
                    "retrieved_at": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "format": "date-time"
                    },
                    "days": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "date": {
                            "type": "string",
                            "format": "date"
                          },
                          "streams": {
                            "type": [
                              "integer",
                              "null"
                            ]
                          }
                        },
                        "required": [
                          "date",
                          "streams"
                        ]
                      }
                    },
                    "state": {
                      "type": "string",
                      "enum": [
                        "comparable",
                        "incomplete",
                        "unfinished_period",
                        "invalid_observation"
                      ]
                    },
                    "missing_days": {
                      "type": "array",
                      "items": {
                        "type": "string",
                        "format": "date"
                      }
                    },
                    "previous_streams": {
                      "type": [
                        "integer",
                        "null"
                      ]
                    },
                    "current_streams": {
                      "type": [
                        "integer",
                        "null"
                      ]
                    },
                    "absolute_growth": {
                      "type": [
                        "integer",
                        "null"
                      ]
                    },
                    "percentage_growth": {
                      "type": [
                        "number",
                        "null"
                      ]
                    },
                    "zero_baseline": {
                      "type": "boolean"
                    },
                    "latest_attempt": {
                      "$ref": "#/components/schemas/CatalogStreamReceipt",
                      "description": "Fresh recording-level receipt for the latest run, including state, observed_days, retrieved_at, source_hash and provider_recording_id. Observation retrieved_at is when its retained version was introduced."
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "400": {
      "description": "Invalid input or incomplete calendar period"
    },
    "401": {
      "description": "Authentication required"
    },
    "404": {
      "description": "Catalog not accessible"
    },
    "503": {
      "description": "Storage, configuration or dispatch unavailable"
    }
  }
}