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.

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