RecoupGet a free auditFree audit

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.

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/research/albums/{id}/measurements'

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 for measurements
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"
          }
        }
      }
    }
  }
}