API REFERENCE

Album measurements

On this page

GET/api/research/albums/{id}/measurements

Latest measured count per track on an album, from the measurement store. {id} is a Spotify album id.

Authentication

See the authentication guide for API key and account access requirements.

Request

cURL

curl --request GET \
  --url 'https://api.recoupable.dev/api/research/albums/YOUR_ID/measurements' \
  --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

idstringrequired

Spotify album id.

Query parameters

platformstring

Platform to read. Currently spotify.

Default: "spotify"

metricstring

Metric to read.

Default: "platform_displayed_play_count"

latestboolean

Return the latest capture per track (the only supported mode today).

Default: true

Responses

200Latest per-track measured counts for the album.

application/json

statusstring

idstring

Spotify album id.

platformstring

metricstring

measurementsarray<ResearchAlbumMeasurementItem>

Item properties

isrcstring

spotify_track_idstringnullable

namestringnullable

valuenumber

Latest measured count.

captured_atstring

format: date-time

data_sourcestring

401Authentication failed — invalid or missing API key.

application/json

statusstring · enumrequired

Values: "error"

errorstringrequired

Human-readable error message describing what went wrong.

402Insufficient credits.

application/json

errorstring · enumrequired

Values: "insufficient_credits"

remaining_creditsintegerrequired

required_creditsintegerrequired

billingUrlstringrequired

Static link to the Recoup app, where a human can save a card and buy credits. It is a constant, not a freshly minted Stripe Checkout Session, so a credit-gated endpoint that keeps returning 402 creates nothing. To buy credits programmatically, call POST /api/credits/sessions.

404No capture exists for this album yet — create a current measurement-job.

application/json

statusstring · enumrequired

Values: "error"

errorstringrequired

Human-readable error message describing what went wrong.

Full specification

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

Download research.json

View operation source

json

{
  "summary": "Album measurements",
  "description": "Latest measured count per track on an album, from the measurement store. `{id}` is a Spotify album id.",
  "parameters": [
    {
      "name": "id",
      "in": "path",
      "required": true,
      "schema": {
        "type": "string"
      },
      "description": "Spotify album id."
    },
    {
      "name": "platform",
      "in": "query",
      "schema": {
        "type": "string",
        "default": "spotify"
      },
      "description": "Platform to read. Currently `spotify`."
    },
    {
      "name": "metric",
      "in": "query",
      "schema": {
        "type": "string",
        "default": "platform_displayed_play_count"
      },
      "description": "Metric to read."
    },
    {
      "name": "latest",
      "in": "query",
      "schema": {
        "type": "boolean",
        "default": true
      },
      "description": "Return the latest capture per track (the only supported mode today)."
    }
  ],
  "responses": {
    "200": {
      "description": "Latest per-track measured counts for the album.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ResearchAlbumMeasurementsResponse"
          }
        }
      }
    },
    "401": {
      "description": "Authentication failed — invalid or missing API key.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ResearchErrorResponse"
          }
        }
      }
    },
    "402": {
      "description": "Insufficient credits.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ResearchInsufficientCreditsResponse"
          }
        }
      }
    },
    "404": {
      "description": "No capture exists for this album yet — create a `current` measurement-job.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ResearchErrorResponse"
          }
        }
      }
    }
  }
}