# Track statistics

Source: https://docs.recoupable.dev/api-reference/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.

## GET /api/research/track/stats

Full OpenAPI specification: https://docs.recoupable.dev/spec/research.json

## Authentication

The supplied specification does not declare an OpenAPI security object for this operation. Its declared headers and parameters still apply. Consult the authentication guide and the full specification before calling it.

[Authentication guide](https://docs.recoupable.dev/authentication)

## Operation and referenced schemas

```json
{
  "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"
    }
  ],
  "paths": {
    "/api/research/track/stats": {
      "get": {
        "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."
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "ResearchTrackStatsResponse": {
        "type": "object",
        "description": "Current per-source track statistics from the Spotify measurement store or the configured research data connection. Provider payloads and coverage vary; inspect per-entry provenance when present.",
        "properties": {
          "status": {
            "type": "string",
            "example": "success"
          },
          "result": {
            "type": "string",
            "example": "success"
          },
          "stats": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ResearchTrackStat"
            }
          }
        }
      },
      "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. Nothing is charged and no Stripe object is created. Credits must be bought explicitly via [`POST /api/credits/sessions`](/api-reference/credits/sessions-create).",
        "properties": {
          "error": {
            "type": "string",
            "enum": [
              "insufficient_credits"
            ]
          },
          "remaining_credits": {
            "type": "integer",
            "example": 0
          },
          "required_credits": {
            "type": "integer",
            "example": 50000
          },
          "billingUrl": {
            "type": "string",
            "description": "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`](/api-reference/credits/sessions-create).",
            "example": "https://app.recoupable.dev"
          }
        },
        "required": [
          "error",
          "remaining_credits",
          "required_credits",
          "billingUrl"
        ]
      },
      "ResearchTrackStat": {
        "type": "object",
        "description": "Per-source current statistics for a single track.",
        "properties": {
          "source": {
            "type": "string",
            "description": "Requested provider platform (for example spotify or apple_music); coverage depends on provider entitlement."
          },
          "data": {
            "type": "object",
            "description": "Provider-specific track counters. A Spotify store streams_total is a platform-displayed play count, not a royalty-bearing stream count.",
            "additionalProperties": true,
            "example": {
              "streams_total": 84213771
            }
          },
          "data_source": {
            "type": "string",
            "description": "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_at": {
            "type": "string",
            "format": "date-time",
            "description": "When this entry's values were captured into the measurement store."
          }
        },
        "additionalProperties": true
      }
    }
  }
}
```