API REFERENCE

Track statistics

On this page

GET/api/research/track/stats

Read current track statistics using exactly one of isrc, spotify_track_id or apple_music_track_id, plus the required platform source. Recoup uses stored Spotify measurements when available for an ISRC and otherwise requests current research data. Fields and coverage vary. Preserve returned data_source and capture timestamps; missing provenance remains unknown.

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?source=spotify' \
  --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 · string

spotify_track_idquery · string

apple_music_track_idquery · string

sourcequery · stringrequired

with_playlistsquery · string

with_chartsquery · string

with_stationsquery · string

with_videosquery · string

with_linksquery · string

only_currentquery · string

limitquery · string

offsetquery · string

cURL for this request

curl --request GET \
  --url 'https://api.recoupable.dev/api/research/track/stats'

Parameters

Query parameters

isrcstring

Supply exactly one track identifier.

spotify_track_idstring

Supply exactly one track identifier.

apple_music_track_idstring

Supply exactly one track identifier.

sourcestringrequired

Required provider source or comma-separated sources; not limited to Spotify.

with_playlistsstring

Optional raw string forwarded unchanged to the configured research data connection. Use true or false per the provider contract; Recoup does not validate or coerce this flag.

with_chartsstring

Optional raw string forwarded unchanged to the configured research data connection. Use true or false per the provider contract; Recoup does not validate or coerce this flag.

with_stationsstring

Optional raw string forwarded unchanged to the configured research data connection. Use true or false per the provider contract; Recoup does not validate or coerce this flag.

with_videosstring

Optional raw string forwarded unchanged to the configured research data connection. Use true or false per the provider contract; Recoup does not validate or coerce this flag.

with_linksstring

Optional raw string forwarded unchanged to the configured research data connection. Use true or false per the provider contract; Recoup does not validate or coerce this flag.

only_currentstring

Optional raw string forwarded unchanged to the configured research data connection. Use true or false per the provider contract; Recoup does not validate or coerce this flag.

limitstring

Optional raw pagination string forwarded unchanged to the configured research data connection. Recoup does not validate its numeric range; provider limits apply.

offsetstring

Optional raw pagination string forwarded unchanged to the configured research data connection. Recoup does not validate its numeric range; provider limits apply.

Responses

200Current per-source track statistics from the measurement store or the configured research data connection, with data_source on recognized stats entries.

application/json

statusstring

Example: "success"

resultstring

Example: "success"

statsarray<ResearchTrackStat>

Item properties

sourcestring

Requested provider platform (for example spotify or apple_music); coverage depends on provider entitlement.

dataobject

Provider-specific track counters. A Spotify store streams_total is a platform-displayed play count, not a royalty-bearing stream count.

Example: {"streams_total":84213771}

data_sourcestring

Opaque provenance label identifying the measurement origin. Preserve this value for traceability. Labels can vary with the data connection and are not a supported vendor selector. Missing provenance remains unknown.

captured_atstring

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

format: date-time

Additional properties

Additional keys are allowed.

400Missing source, or zero/multiple track identifiers. Supply exactly one of the four supported identifiers.

application/json

statusstring · enumrequired

Values: "error"

Example: "error"

errorstringrequired

Human-readable error message describing what went wrong.

Example: "Missing required parameter: artist"

401Authentication failed — invalid or missing API key.

application/json

statusstring · enumrequired

Values: "error"

Example: "error"

errorstringrequired

Human-readable error message describing what went wrong.

Example: "Missing required parameter: artist"

402Insufficient research credits — the body includes a static billingUrl. No Stripe object is created.

application/json

errorstring · enumrequired

Values: "insufficient_credits"

remaining_creditsintegerrequired

Example: 0

required_creditsintegerrequired

Example: 50000

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.

Example: "https://app.recoupable.dev"

404Requested track or source data was not found by the provider.

application/json

statusstring · enumrequired

Values: "error"

Example: "error"

errorstringrequired

Human-readable error message describing what went wrong.

Example: "Missing required parameter: artist"

429Provider rate/quota limit; do not retry in an unbounded loop.

No response body schema is specified.

500Missing provider configuration, transport failure or internal error.

No response body schema is specified.

504the configured research data connection request timed out.

No response body schema is specified.

Full specification

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

Download research.json

View operation source

json

{
  "operationId": "getResearchTrackStats",
  "description": "Read current track statistics using exactly one of `isrc`, `spotify_track_id` or `apple_music_track_id`, plus the required platform `source`. Recoup uses stored Spotify measurements when available for an ISRC and otherwise requests current research data. Fields and coverage vary. Preserve returned `data_source` and capture timestamps; missing provenance remains unknown.",
  "parameters": [
    {
      "name": "isrc",
      "in": "query",
      "required": false,
      "schema": {
        "type": "string"
      },
      "description": "Supply exactly one track identifier.",
      "example": "USQY51771120"
    },
    {
      "name": "spotify_track_id",
      "in": "query",
      "required": false,
      "schema": {
        "type": "string"
      },
      "description": "Supply exactly one track identifier."
    },
    {
      "name": "apple_music_track_id",
      "in": "query",
      "required": false,
      "schema": {
        "type": "string"
      },
      "description": "Supply exactly one track identifier."
    },
    {
      "name": "source",
      "in": "query",
      "required": true,
      "schema": {
        "type": "string"
      },
      "description": "Required provider source or comma-separated sources; not limited to Spotify.",
      "example": "spotify"
    },
    {
      "name": "with_playlists",
      "in": "query",
      "required": false,
      "schema": {
        "type": "string"
      },
      "description": "Optional raw string forwarded unchanged to the configured research data connection. Use true or false per the provider contract; Recoup does not validate or coerce this flag.",
      "example": "true"
    },
    {
      "name": "with_charts",
      "in": "query",
      "required": false,
      "schema": {
        "type": "string"
      },
      "description": "Optional raw string forwarded unchanged to the configured research data connection. Use true or false per the provider contract; Recoup does not validate or coerce this flag.",
      "example": "true"
    },
    {
      "name": "with_stations",
      "in": "query",
      "required": false,
      "schema": {
        "type": "string"
      },
      "description": "Optional raw string forwarded unchanged to the configured research data connection. Use true or false per the provider contract; Recoup does not validate or coerce this flag.",
      "example": "true"
    },
    {
      "name": "with_videos",
      "in": "query",
      "required": false,
      "schema": {
        "type": "string"
      },
      "description": "Optional raw string forwarded unchanged to the configured research data connection. Use true or false per the provider contract; Recoup does not validate or coerce this flag.",
      "example": "true"
    },
    {
      "name": "with_links",
      "in": "query",
      "required": false,
      "schema": {
        "type": "string"
      },
      "description": "Optional raw string forwarded unchanged to the configured research data connection. Use true or false per the provider contract; Recoup does not validate or coerce this flag.",
      "example": "true"
    },
    {
      "name": "only_current",
      "in": "query",
      "required": false,
      "schema": {
        "type": "string"
      },
      "description": "Optional raw string forwarded unchanged to the configured research data connection. Use true or false per the provider contract; Recoup does not validate or coerce this flag.",
      "example": "true"
    },
    {
      "name": "limit",
      "in": "query",
      "required": false,
      "schema": {
        "type": "string"
      },
      "description": "Optional raw pagination string forwarded unchanged to the configured research data connection. Recoup does not validate its numeric range; provider limits apply.",
      "example": "50"
    },
    {
      "name": "offset",
      "in": "query",
      "required": false,
      "schema": {
        "type": "string"
      },
      "description": "Optional raw pagination string forwarded unchanged to the configured research data connection. Recoup does not validate its numeric range; provider limits apply.",
      "example": "0"
    }
  ],
  "responses": {
    "200": {
      "description": "Current per-source track statistics from the measurement store or the configured research data connection, with data_source on recognized stats entries.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ResearchTrackStatsResponse"
          }
        }
      }
    },
    "400": {
      "description": "Missing source, or zero/multiple track identifiers. Supply exactly one of the four supported identifiers.",
      "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": "Requested track or source data was not found by the provider.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ResearchErrorResponse"
          }
        }
      }
    },
    "429": {
      "description": "Provider rate/quota limit; do not retry in an unbounded loop."
    },
    "500": {
      "description": "Missing provider configuration, transport failure or internal error."
    },
    "504": {
      "description": "the configured research data connection request timed out."
    }
  }
}