RecoupGet a free auditFree audit

API REFERENCE

Track measurements

On this page
GET/api/research/tracks/{id}/measurements

Time-series of a track's measured counts.

Authentication

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

Request

cURL
curl --request GET \
  --url 'https://api.recoupable.dev/api/research/tracks/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/tracks/{id}/measurements'

Parameters

Path parameters

idstringrequired

Provider-neutral track id — ISRC or Spotify track id.

Query parameters

platformstring

Platform to read. Currently spotify.

Default: "spotify"

metricstring

Metric to read.

Default: "platform_displayed_play_count"

fromstring

Inclusive start date (ISO) for the series.

tostring

Inclusive end date (ISO) for the series.

granularitystring · enum

Series granularity. daily returns the per-day cumulative series.

Values: "daily"

Default: "daily"

aggregatestring · enum

Return a derived aggregate instead of the raw series. run_rate returns the trailing-window annualized run-rate (a projection of the series).

Values: "run_rate"

windowstring

Trailing window for aggregate=run_rate (e.g. 365d).

Default: "365d"

Responses

200The measurement series (or the requested aggregate).

application/json

statusstring
idstring

The provider-neutral track id queried.

platformstring
metricstring
seriesarray<ResearchMeasurementPoint>

Present unless aggregate is set.

Item properties for series
datestring

format: date

valuenumber

Cumulative metric value as of date.

data_sourcestring
aggregateobjectnullable

Present when aggregate=run_rate.

Properties for aggregate
kindstring
window_daysinteger
deltanumber
run_rate_annualizednumber
400Validation error — bad identifier or query param.

application/json

statusstring · enumrequired

Values: "error"

errorstringrequired

Human-readable error message describing what went wrong.

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 measurements for this track yet — create a current measurement job to capture it.

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": "Track measurements",
  "description": "Time-series of a track's measured counts.",
  "parameters": [
    {
      "name": "id",
      "in": "path",
      "required": true,
      "schema": {
        "type": "string"
      },
      "description": "Provider-neutral track id — ISRC or Spotify track 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": "from",
      "in": "query",
      "schema": {
        "type": "string",
        "format": "date"
      },
      "description": "Inclusive start date (ISO) for the series."
    },
    {
      "name": "to",
      "in": "query",
      "schema": {
        "type": "string",
        "format": "date"
      },
      "description": "Inclusive end date (ISO) for the series."
    },
    {
      "name": "granularity",
      "in": "query",
      "schema": {
        "type": "string",
        "enum": [
          "daily"
        ],
        "default": "daily"
      },
      "description": "Series granularity. `daily` returns the per-day cumulative series."
    },
    {
      "name": "aggregate",
      "in": "query",
      "schema": {
        "type": "string",
        "enum": [
          "run_rate"
        ]
      },
      "description": "Return a derived aggregate instead of the raw series. `run_rate` returns the trailing-window annualized run-rate (a projection of the series)."
    },
    {
      "name": "window",
      "in": "query",
      "schema": {
        "type": "string",
        "default": "365d"
      },
      "description": "Trailing window for `aggregate=run_rate` (e.g. `365d`)."
    }
  ],
  "responses": {
    "200": {
      "description": "The measurement series (or the requested aggregate).",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ResearchMeasurementsResponse"
          }
        }
      }
    },
    "400": {
      "description": "Validation error — bad identifier or query param.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ResearchErrorResponse"
          }
        }
      }
    },
    "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 measurements for this track yet — create a `current` measurement job to capture it.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ResearchErrorResponse"
          }
        }
      }
    }
  }
}