> ## Documentation Index > Fetch the complete documentation index at: https://docs.recoupable.dev/llms.txt > Use this file to discover all available pages before exploring further. # Track Stats > Get per-track, per-source current stats by ISRC or track id — absolute `streams_total`, playlist reach, and chart counts. ## OpenAPI ````yaml api-reference/openapi/research.json GET /api/research/track/stats openapi: 3.1.0 info: title: Recoup API - Research description: >- API documentation for the Recoup platform - an AI agent platform for the music industry license: name: MIT version: 1.0.0 servers: - url: https://api.recoupable.dev security: [] paths: /api/research/track/stats: get: description: >- Get per-track, per-source current stats by ISRC or track id — absolute `streams_total`, playlist reach, and chart counts. parameters: - name: isrc in: query required: false description: Track ISRC. Provide exactly one track identifier. schema: type: string example: USQY51771120 - name: songstats_track_id in: query required: false description: Songstats track id (from `GET /api/research/tracks`). schema: type: string - name: spotify_track_id in: query required: false description: Spotify track id. schema: type: string - name: apple_music_track_id in: query required: false description: Apple Music track id. schema: type: string - name: source in: query required: true description: >- Comma-separated list of sources, or `all`. e.g. `spotify`, `apple_music`, `deezer`, `youtube`. schema: type: string example: spotify - name: with_playlists in: query required: false description: Include the per-source `playlists[]` array in `data`. schema: type: boolean - name: with_charts in: query required: false description: Include the per-source `charts[]` array in `data`. schema: type: boolean - name: with_stations in: query required: false description: Include radio `stations[]` data where available. schema: type: boolean - name: with_videos in: query required: false description: Include video data where available. schema: type: boolean - name: with_links in: query required: false description: Include external links where available. schema: type: boolean - name: only_current in: query required: false description: >- Return only current counters, omitting historical/total breakdowns where applicable. schema: type: boolean - name: limit in: query required: false description: Max items in toggled arrays (e.g. `playlists[]`). schema: type: integer - name: offset in: query required: false description: Pagination offset for toggled arrays. schema: type: integer responses: '200': description: Per-track current stats, one entry per requested source. content: application/json: schema: $ref: '#/components/schemas/ResearchTrackStatsResponse' '400': description: Validation error — missing identifier or `source`. 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 `checkoutUrl` to top up. content: application/json: schema: $ref: '#/components/schemas/ResearchInsufficientCreditsResponse' '404': description: No track matched the supplied identifier. content: application/json: schema: $ref: '#/components/schemas/ResearchErrorResponse' '429': description: >- Upstream provider error passthrough — e.g. 429 when the Songstats quota is exhausted. content: application/json: schema: $ref: '#/components/schemas/ResearchErrorResponse' components: schemas: ResearchTrackStatsResponse: type: object description: >- Per-track current statistics for the requested `source`(s). Mirrors `ResearchMetricsResponse`, scoped to a single recording. When every requested source is store-served, the response is the minimal envelope `{ result, stats }` — `track_info`, `source_ids`, and `message` appear only when Songstats served part of the request. properties: status: type: string example: success result: type: string example: success message: type: string example: Data Retrieved. stats: type: array items: $ref: '#/components/schemas/ResearchTrackStat' track_info: $ref: '#/components/schemas/ResearchTrackInfo' source_ids: type: array description: >- All source identifiers Songstats tracks for this recording — a superset of the sources returned in `stats`. items: type: string ResearchErrorResponse: type: object required: - status - error description: >- Error response returned by all research endpoints for validation failures (400) and authentication errors (401). properties: status: type: string enum: - error example: error error: type: string description: Human-readable error message describing what went wrong. example: 'Missing required parameter: artist' ResearchInsufficientCreditsResponse: type: object description: >- Returned (402) when the account lacks research credits and auto-recharge did not cover the call. properties: error: type: string enum: - insufficient_credits remaining_credits: type: integer example: 0 required_credits: type: integer example: 5 checkoutUrl: type: string description: Stripe checkout link to top up credits. declineReason: type: string description: Card decline reason when auto-recharge was attempted and failed. required: - error - remaining_credits - required_credits - checkoutUrl ResearchTrackStat: type: object description: Per-source current statistics for a single track. properties: source: type: string description: >- Platform the stats belong to, e.g. `spotify`, `apple_music`, `deezer`, `youtube`. data: type: object description: >- Per-source counters for this track. `streams_total` is the absolute play count. Keys vary by `source`; optional `playlists[]` / `charts[]` / `reposters[]` arrays appear when the matching `with_*` toggle is set. Store-served (apify) entries carry only `streams_total` — a platform-displayed play count, not a royalty-bearing stream count. additionalProperties: true example: streams_total: 84213771 popularity_current: 64 playlists_current: 1200 playlists_total: 4830 playlist_reach_current: 18450201 playlist_reach_total: 51200988 charts_current: 3 charts_total: 41 shazams_total: 220145 charted_cities_total: 87 charted_countries_total: 23 favorites_total: 0 reposts_total: 0 engagement_rate_total: 0 playlists_editorial_current: 12 playlists_editorial_total: 58 data_source: type: string description: >- Provenance of the numbers: `apify_spotify_playcount` (platform-displayed count from the measurement store), `songstats` (Songstats backfill), or `granted_analytics` (customer-granted data). example: apify_spotify_playcount captured_at: type: string format: date-time description: >- When this entry's values were captured into the measurement store. Present only on store-served entries (`data_source: "apify_spotify_playcount"`). additionalProperties: true ResearchTrackInfo: type: object description: Full track record. properties: songstats_track_id: type: string description: >- Songstats track id — pass to `GET /api/research/track/stats` or `GET /api/research/track`. title: type: string avatar: type: string site_url: type: string release_date: type: string nullable: true artists: type: array items: $ref: '#/components/schemas/ResearchArtistMini' is_remix: type: boolean collaborators: type: array items: $ref: '#/components/schemas/ResearchCollaborator' labels: type: array items: type: object additionalProperties: true distributors: type: array items: type: object properties: name: type: string additionalProperties: true genres: type: array items: type: string links: type: array items: $ref: '#/components/schemas/ResearchLink' additionalProperties: true ResearchArtistMini: type: object description: Minimal artist reference embedded in catalog/activity payloads. properties: name: type: string additionalProperties: true ResearchCollaborator: type: object properties: name: type: string roles: type: array items: type: string additionalProperties: true ResearchLink: type: object description: External platform link. properties: source: type: string description: Platform name, e.g. `spotify`, `apple_music`. external_id: type: string description: Platform-specific ID. url: type: string isrc: type: string description: ISRC (tracks only). additionalProperties: true ````