API REFERENCE

Track Stats

On this page

GET/api/research/track/stats

Get the current Spotify play count for one recording by ISRC, served from the Apify-backed measurement store. A fresh capture is returned as-is; a stale or missing one triggers a refresh of the recording's album through the Spotify play-count actor before responding.

Authentication

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

Request

cURL

curl --request GET \
  --url 'https://api.recoupable.dev/api/research/track/stats?isrc=USQY51771120' \
  --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.

API keyx-api-key header

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

isrcquery · stringrequired

sourcequery · string

cURL for this request

curl --request GET \
  --url 'https://recoup-api.vercel.app/api/research/track/stats'

Parameters

Query parameters

isrcstringrequired

Track ISRC. The recording must have a Spotify album mapping in the measurement store (created by a current measurement job or a catalog snapshot).

sourcestring · enum

Only spotify is supported; defaults to spotify.

Values: "spotify"

Default: "spotify"

Responses

200The recording's current Spotify play count from the measurement store.

application/json

statusstring

resultstring

statsarray<ResearchTrackStat>

Item properties

sourcestring

Platform the stats belong to — spotify.

dataobject

Per-source counters for this track. streams_total is the platform-displayed play count from the measurement store, not a royalty-bearing stream count.

data_sourcestring

Provenance of the numbers: apify_spotify_playcount (platform-displayed count from the measurement store) or granted_analytics (customer-granted data).

captured_atstring

When this entry's values were captured into the measurement store.

format: date-time

Additional properties

Additional keys are allowed.

400Validation error — isrc missing, or source is not spotify.

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 research credits — the body includes a static billingUrl. No Stripe object is created.

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.

404Nothing stored for this ISRC and no Spotify album mapping to refresh from — create a current measurement job for it first.

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

{
  "description": "Get the current Spotify play count for one recording by ISRC, served from the Apify-backed measurement store. A fresh capture is returned as-is; a stale or missing one triggers a refresh of the recording's album through the Spotify play-count actor before responding.",
  "parameters": [
    {
      "name": "isrc",
      "in": "query",
      "required": true,
      "description": "Track ISRC. The recording must have a Spotify album mapping in the measurement store (created by a `current` measurement job or a catalog snapshot).",
      "schema": {
        "type": "string",
        "example": "USQY51771120"
      }
    },
    {
      "name": "source",
      "in": "query",
      "required": false,
      "description": "Only `spotify` is supported; defaults to `spotify`.",
      "schema": {
        "type": "string",
        "enum": [
          "spotify"
        ],
        "default": "spotify"
      }
    }
  ],
  "responses": {
    "200": {
      "description": "The recording's current Spotify play count from the measurement store.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ResearchTrackStatsResponse"
          }
        }
      }
    },
    "400": {
      "description": "Validation error — `isrc` missing, or `source` is not `spotify`.",
      "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 research credits — the body includes a static `billingUrl`. No Stripe object is created.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ResearchInsufficientCreditsResponse"
          }
        }
      }
    },
    "404": {
      "description": "Nothing stored for this ISRC and no Spotify album mapping to refresh from — create a `current` measurement job for it first.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ResearchErrorResponse"
          }
        }
      }
    }
  }
}