# Research availability

Source: https://recoupable.dev/docs/research-availability

Explore Recoup research, choose the right identifiers, and handle incomplete data.

Recoup Research lets you discover artists and tracks, read current metrics,
explore audience and playlist activity, and capture recording measurements.
Authenticate with your Recoup API key or supported bearer credential. Recoup
manages the data connections; you do not need a separate data-service key.

Coverage varies by artist, recording, platform and metric. An empty result means
no matching data was returned; it does not prove an artist has no activity or audience.

## Choose an identifier

Search by name, inspect the matches, and pass the selected result's `id` to the
detail endpoints. Treat research IDs as opaque strings: do not parse them or
substitute a Recoup account UUID. Artist-name shortcuts use the first match;
select an explicit ID when names are ambiguous.

For portable recording references, store the ISRC and available Spotify or
Apple Music identifiers. Additional response fields and provenance labels may
vary as Recoup's data connections change. Preserve returned provenance for
traceability without using it to choose a data vendor.

## Current track statistics

Supply exactly one of `isrc`, `spotify_track_id`, or `apple_music_track_id`, plus
the required `source` (the platform, such as `spotify`). Recoup uses stored
Spotify measurements when available for an ISRC, and otherwise requests current
research data. Preserve `data_source` and capture timestamps when returned;
missing provenance remains unknown. A displayed play count is not a verified
royalty-bearing stream count.

## Research endpoints

| Method | Path | Reference |
| --- | --- | --- |
| GET | `/api/research` | [Search](https://recoupable.dev/docs/api-reference/research/search) |
| GET | `/api/research/albums` | [Albums](https://recoupable.dev/docs/api-reference/research/albums) |
| GET | `/api/research/audience` | [Audience](https://recoupable.dev/docs/api-reference/research/audience) |
| GET | `/api/research/career` | [Career activities](https://recoupable.dev/docs/api-reference/research/career) |
| GET | `/api/research/insights` | [Insights activities](https://recoupable.dev/docs/api-reference/research/insights) |
| GET | `/api/research/lookup` | [Spotify artist lookup](https://recoupable.dev/docs/api-reference/research/lookup) |
| GET | `/api/research/metrics` | [Current artist metrics](https://recoupable.dev/docs/api-reference/research/metrics) |
| GET | `/api/research/milestones` | [Milestones](https://recoupable.dev/docs/api-reference/research/milestones) |
| GET | `/api/research/playlists` | [Artist playlists](https://recoupable.dev/docs/api-reference/research/playlists) |
| GET | `/api/research/profile` | [Artist profile](https://recoupable.dev/docs/api-reference/research/profile) |
| GET | `/api/research/similar` | [Related artists](https://recoupable.dev/docs/api-reference/research/similar) |
| GET | `/api/research/track` | [Track details](https://recoupable.dev/docs/api-reference/research/track) |
| GET | `/api/research/track/playlists` | [Track playlists](https://recoupable.dev/docs/api-reference/research/track-playlists) |
| GET | `/api/research/tracks` | [Artist tracks](https://recoupable.dev/docs/api-reference/research/tracks) |
| GET | `/api/research/urls` | [Platform URLs](https://recoupable.dev/docs/api-reference/research/urls) |

## Understand the results

- Artist metrics are current snapshots. Save dated results to compare them over time.
- Related artists are unweighted; the accepted similarity axes do not change the ranking.
- Artist playlist `status=past` uses all-time scope and can include current placements.
- Career, insights and milestones expose available activities. They do not calculate a career score, create an AI report or guarantee a complete timeline.
- Album results can include track-shaped catalog entries. Do not assume every entry is a distinct album.
- Pagination and track-playlist filter behavior depend on the available data connection. Check the returned entries before assuming a filter was applied.

## Historical measurement jobs

`POST /api/research/measurement-jobs` supports `source: "historical"`
for Spotify backfill. It requires a card on file and returns queue counts with
`id: null`; enqueueing does not confirm capture completion. Recordings with an
existing historical research measurement can be skipped even when their history
is partial. Inspect the available dates before claiming complete coverage.
Current capture jobs return a snapshot ID.

## Costs and unavailable data

Successful research calls cost $0.05 (50,000 micro-dollar credits). Track-name
resolution can add separately charged lookup calls; reuse a selected research
ID when available. Historical enqueue itself does not deduct research credits;
capture work has its own balance and budget checks.

For `402 insufficient_credits`, show the returned `billingUrl`. Surface `429`
and unavailable-data errors; use bounded retries for transient failures and stop
when the request cannot be served. Recoup does not promise a `Retry-After` header
on these routes. Never fill a missing metric with an invented number or zero.