← API reference

Statistics

Aggregations, charts, personality.

36 of 36 · v0.132.2
GET /api/v1/stats/dashboard #
Token reador Session

Dashboard counters.

Scope: read (since v0.39). "Today" and "this week" are bucketed in the user's own timezone and honour their week-start preference.

Deliberately does not carry distinct artist, album or track counts. It used to compute all three, each a COUNT(DISTINCT) building a temp B-tree over the whole history, on the most-loaded page in the application — and nothing rendered any of them. GET /api/v1/stats answers the same question against a range control, which is where it belongs.

Responses

200

OK.

application/json

object

The home screen's numbers. "Today" and "this week" are in your own timezone, and the week starts on the day your preferences say.

today integer · int64 required
this_week integer · int64 required
total integer · int64 required
lossless_pct integer · int64 required

A whole percentage of fidelity_known, not of total.

fidelity_known integer · int64 required

Listens whose format is known — the population lossless_pct is a share of. When that is a small slice, show the coverage rather than the percentage: a 94% computed from 558 of 21,390 listens is a fact about the 558.

top_artist string required

The most-played artist of the last 30 days, or — with none.

top_artist_count integer · int64 required
total_hours number · double required
today_hours number · double required
week_hours number · double required
avg_quality number · double required

Over the listens that carry a score; 0 with none.

401

No valid session cookie or token. Also returned when a token is presented to a session-only endpoint — the endpoint does not accept tokens at all, so the scope is irrelevant.

application/json

object

Every error body in the API has this shape.

code integer · int32 required

Mirrors the HTTP status.

error string required

Human-readable. Not a stable identifier — do not branch on it.

{
  "code": 401,
  "error": "Authentication required. Log in to access this endpoint."
}
403

Authenticated, but not permitted. Either the token lacks the required scope, or the endpoint needs the admin role. Deliberately not a 401 — re-authenticating will not help.

application/json

object

Every error body in the API has this shape.

code integer · int32 required

Mirrors the HTTP status.

error string required

Human-readable. Not a stable identifier — do not branch on it.

{
  "code": 403,
  "error": "This token does not have the 'write' scope"
}
GET /api/v1/stats #
Token reador Session

Ranged statistics.

Scope: read (since v0.39). Totals, top lists (50 rows each), fidelity mix, decades, a 7×24 listening heatmap, breadth, genres and languages.

The genre breakdown is a share of tag mentions, not listens — one track carries several tags. Never present it as a percentage of plays.

Parameters

range query

The window, rolling back from now: today, d7 (or week), month (or last30), year, or all, the default. Anything else is all time.

string
metric query

plays (default) or hours. How the three top lists are ranked, not merely what number is shown. They are cut to 50 rows server-side, so re-sorting in the client would only reorder the top 50 by plays and would miss a long record played a handful of times — which is exactly the row switching to hours exists to surface. Listens whose source reported no duration count as zero and sort last.

string

Responses

200

OK.

application/json

object

Ranged statistics: totals, top lists (50 rows each), fidelity mix, decades, a 7×24 listening heatmap, breadth, genres and languages.

totals object required
plays integer · int64 required
hours number · double required

Summed over the listens with a known length — see duration_known.

duration_known integer · int64 required

Listens hours is summed over. A listen whose source reported no length contributes nothing, so hours is a floor rather than a total.

artists integer · int64 required
albums integer · int64 required
tracks integer · int64 required
avg_quality number · double required

0–100, averaged over quality_known listens only; 0 when there are none.

quality_known integer · int64 required

Listens avg_quality is averaged over. Only a live source ever writes a quality score, so an imported history has none and the average is over the same narrow population the fidelity shares are. Present it with its coverage or not at all; at zero there is no score to show, not a score of zero.

lossless_pct integer · int64 required

Share of fidelity_known, not of plays. A whole percentage.

dsd_pct integer · int64 required

Share of fidelity_known, not of plays. A whole percentage.

fidelity_known integer · int64 required

Listens in this window whose format is known — the denominator of the two shares above. The fidelity array is a share of plays instead, because it carries an Unknown bucket of its own.

skips integer · int64 required

Skipped plays in this window. Every other count in this object excludes them; this one is about them. Not every source reports skips, so zero means "nothing told us", not "nothing skipped".

per_day number · double required

Plays per calendar day of the window, including days with no listening. Dividing by active days instead reports a busy afternoon's rate as the year's.

first_listen integer | null · int64

Earliest non-skipped listen, unix seconds. A fact about the whole history and therefore not ranged — asking it of a one-week window would only restate the window.

loves integer · int64 required

Loved entities: tracks, records and artists together. All time, not ranged.

top_artists array required
each item
object

A top artist. Counted over everyone credited, the way the charts count.

name string required
plays integer · int64 required
hours number · double required

One decimal place.

image_url string | null
top_albums array required
each item
object
name string required
artist string required
plays integer · int64 required
hours number · double required

One decimal place.

top_tracks array required
each item
object
title string required
artist string required
artist_credit string | null

Everyone credited, "; "-joined and primary first, when there is more than one. artist is the primary alone.

album string | null
album_artist string | null

Who album is filed under, which opens it.

plays integer · int64 required
hours number · double required

One decimal place.

fidelity array required

DSD, Lossless, Lossy and Unknown, largest first. A share of plays, because it carries the Unknown bucket of its own.

each item
object

One slice of a breakdown.

name string required
plays integer · int64 required
pct integer · int64 required

A whole percentage of the breakdown's own total — which total, each breakdown says.

decades array required

Release decades, 1970s and so on, oldest first. Only listens whose release year has been resolved count, so pct is a share of those.

each item
object

One slice of a breakdown.

name string required
plays integer · int64 required
pct integer · int64 required

A whole percentage of the breakdown's own total — which total, each breakdown says.

genres array required

The twelve most-mentioned genres. A share of tag mentions, not listens — one track carries several tags. Never present it as a percentage of plays.

each item
object

One slice of a breakdown.

name string required
plays integer · int64 required
pct integer · int64 required

A whole percentage of the breakdown's own total — which total, each breakdown says.

languages array required

The twelve largest languages, over the listens that have been classified.

each item
object
name string required
pct integer · int64 required

A whole percentage of the classified listens.

regions array required

Always empty; reserved.

each item
object
heatmap array required

Seven rows of 24, counts of plays by hour, in your own timezone. Row 0 is Monday.

each item
array
each item
integer · int64
breadth object | null

Absent until the genre map is fetched and genres backfilled — "you play 0 genres" would be a lie about the listening rather than a statement about the data.

genres_played integer required
genres_placed integer | null

Of those, the ones the map places.

effective_genres number | null · double

exp(H) over play counts — as varied as playing N genres equally.

evenness number | null · double

effective_genres over genres_played, 0–1. 1.0 would mean every genre played exactly equally.

reach number | null · double

Your play-weighted spread over the map's own spread, 0–1. Null when nothing played is on the map.

401

No valid session cookie or token. Also returned when a token is presented to a session-only endpoint — the endpoint does not accept tokens at all, so the scope is irrelevant.

application/json

object

Every error body in the API has this shape.

code integer · int32 required

Mirrors the HTTP status.

error string required

Human-readable. Not a stable identifier — do not branch on it.

{
  "code": 401,
  "error": "Authentication required. Log in to access this endpoint."
}
403

Authenticated, but not permitted. Either the token lacks the required scope, or the endpoint needs the admin role. Deliberately not a 401 — re-authenticating will not help.

application/json

object

Every error body in the API has this shape.

code integer · int32 required

Mirrors the HTTP status.

error string required

Human-readable. Not a stable identifier — do not branch on it.

{
  "code": 403,
  "error": "This token does not have the 'write' scope"
}
GET /api/v1/stats/graphs #
Token reador Session

Statistics graphs.

Scope: read (since v0.130). Daily volume, obsession waves, the long tail, sessions, first listens, habit-vs-burst, album spread and anchor songs, for one range. Days are bucketed in your own timezone.

Artists are everyone credited, so the artist figures are shares of artist credits, not of listens — a listen with two artists counts once for each. volume and sessions count listens.

Parameters

range query

The window, rolling back from now: week, month (or last30), year, or all, the default. Anything else is all time.

string

Responses

200

OK.

application/json

object
range string required

The range asked for: week, month, last30, year or all.

timezone string required

The IANA zone every day below is bucketed in.

capped boolean required

True when the history was longer than this server reads in one pass (scaled to its memory). The oldest listens are the ones left out.

start_day string | null

First local day of the axis, YYYY-MM-DD. Absent when the range is empty. Every daily array below starts here, one entry per day.

daily array required

Listens per local day, from start_day to today, including days with none.

each item
integer · int64
volume object required
plays integer · int64 required

Listens in the range.

active_days integer · int64 required

Days in the range with at least one listen.

median_active_day number · double required

Median listens on a day you listened at all. Zero-listen days are left out on purpose: they would drag the median of a sparse history to 0.

peak object | null

The busiest day in the range.

day string required

YYYY-MM-DD, local.

plays integer · int64 required
waves array required

The most-credited artists in the range, with their own daily counts on the same axis as daily.

each item
object
name string required
plays integer · int64 required

Credited plays in the range.

daily array required

Credited plays per local day, aligned with StatsGraphs::daily.

each item
integer · int64
long_tail object required
counts array required

Credited plays per artist, largest first. The curve is their running sum over credits.

each item
integer · int64
credits integer · int64 required

The sum of counts: artist credits, not listens — a listen with two artists credited counts once for each.

once integer · int64 required

Artists heard exactly once in the range.

hundred_plus integer · int64 required

Artists heard 100 times or more in the range.

half integer · int64 required

How many of the top artists it takes to reach half of credits.

eighty integer · int64 required

How many of the top artists it takes to reach 80% of credits.

sessions object required
total integer · int64 required

Sessions in the range. A gap longer than gap_minutes starts a new one.

gap_minutes integer · int64 required
lengths array required

Sessions by how many listens they held, in fixed buckets.

each item
object
label string required

1, 2, 3–4, 5–9, 10–19, 20–49, 50–99 or 100+.

sessions integer · int64 required
devotion object required

How much of each session went to its most-played artist.

Measured over sessions of at least min_listens, and over the primary artist of each listen — fanning credits out here would let one session's shares add up to more than everything played in it.

min_listens integer · int64 required
devoted integer · int64 required

One artist took 80% or more of the session.

mixed integer · int64 required

The top artist took 40–80%.

scattered integer · int64 required

No artist took as much as 40%.

first_listens array required

The range's most-credited artists, ordered by when you first heard them — across the whole history, not the range.

each item
object
name string required
plays integer · int64 required

Credited plays in the range.

first integer · int64 required

First listen ever, unix seconds — not ranged.

last integer · int64 required

Most recent listen, unix seconds — not ranged.

loyalty number · double required

0–100. High is steady, recurring listening; low is bursts.

habits array required

Daily habit or burst: how each artist's listening is spread over time. Only artists with five or more plays on at least two different days.

each item
object
name string required
plays integer · int64 required

Credited plays in the range.

active_days integer · int64 required

Days in the range this artist was played.

span_days integer · int64 required

Days from their first to their last listen in the range, inclusive.

return_rate number · double required

active_days / span_days: how often they come back. 1 = every day.

top_day_share number · double required

Share of their plays on their single biggest day. 1 = all on one day.

top_day string required

That biggest day, YYYY-MM-DD.

loyalty number · double required

0–100. High is steady, recurring listening; low is bursts.

albums array required

How each top artist's plays split across their records.

each item
object
name string required
plays integer · int64 required

Credited plays in the range.

album_count integer · int64 required

Distinct records those plays were on.

albums array required

The most-played records, largest first, at most five.

each item
object
name string required
album_artist string required

Who the record is filed under, which is what opens it.

plays integer · int64 required
rest_plays integer · int64 required

Plays on every other record.

no_album integer · int64 required

Plays whose source named no record at all.

anchors array required

Artists you mostly play one song from, most anchored first.

each item
object
name string required
plays integer · int64 required

Credited plays in the range.

title string required

The one song most of them are.

title_plays integer · int64 required
share number · double required

title_plays / plays.

tracks integer · int64 required

How many different songs of theirs were played at all.

401

No valid session cookie or token. Also returned when a token is presented to a session-only endpoint — the endpoint does not accept tokens at all, so the scope is irrelevant.

application/json

object

Every error body in the API has this shape.

code integer · int32 required

Mirrors the HTTP status.

error string required

Human-readable. Not a stable identifier — do not branch on it.

{
  "code": 401,
  "error": "Authentication required. Log in to access this endpoint."
}
403

Authenticated, but not permitted. Either the token lacks the required scope, or the endpoint needs the admin role. Deliberately not a 401 — re-authenticating will not help.

application/json

object

Every error body in the API has this shape.

code integer · int32 required

Mirrors the HTTP status.

error string required

Human-readable. Not a stable identifier — do not branch on it.

{
  "code": 403,
  "error": "This token does not have the 'write' scope"
}
GET /api/v1/personality #
Token reador Session

Musical personality — a verdict, traits and loyalty.

Scope: read (since v0.120).

Parameters

range query

The window, rolling back from now: today, d7 (or week), month (or last30), year, or all, the default. Anything else is all time.

string
metric query

plays (default) or hours. How the three top lists are ranked, not merely what number is shown. They are cut to 50 rows server-side, so re-sorting in the client would only reorder the top 50 by plays and would miss a long record played a handful of times — which is exactly the row switching to hours exists to surface. Listens whose source reported no duration count as zero and sort last.

string

Responses

200

OK.

application/json

object
verdict string required
traits array required
each item
object
label string required
low string required
high string required
score number · double required
evidence string required
loyalty array required
each item
object
artist string required
plays integer · int64 required
loyalty_score number · double required
total_plays integer required
401

No valid session cookie or token. Also returned when a token is presented to a session-only endpoint — the endpoint does not accept tokens at all, so the scope is irrelevant.

application/json

object

Every error body in the API has this shape.

code integer · int32 required

Mirrors the HTTP status.

error string required

Human-readable. Not a stable identifier — do not branch on it.

{
  "code": 401,
  "error": "Authentication required. Log in to access this endpoint."
}
GET /api/v1/lyrics #
Token reador Session

The words to one track, as numbered lines.

Scope: read.

Numbered including blank lines. A stanza break is a line, because a liner note refers to a line by its index — [[line:12]] or [[line:A:3:12]] — and skipping empties would renumber every line after one, silently re-pointing every quote already written.

Never triggers an LRCLIB fetch. That service is free and asks callers to be considerate; the backfill is what paces it, and a screen that fetched on open would let a page refresh drive the rate.

It does reach the user's own media server when nothing is stored yet. Their Plex or Jellyfin has no rate limit and no shared budget to spend, and they tag their own albums — so those words are usually right there while the LRCLIB trickle is still hours from this track. Only when the cache holds nothing: a stored lyric is never re-fetched on a page load.

Three answers, all real: lines, instrumental: true (a track with no words, which is not a gap), and an empty list.

Lyrics are the provider's text. They are cached outside the listening database, so GET /api/v1/backup does not carry them, and they are not served by the public now-playing endpoint or by Patch.

Parameters

artist query required
string
title query required
string
album query

Which record to draw the tracklist from.

Optional and resolved from the history when it is absent, because the caller is usually a note or a history row that knows the track and not the record it was filed under. Passed explicitly it wins, since a track on three compilations has three honest answers and only the caller knows which one is being read.

string

Responses

200

OK — including for a track nothing is held for.

application/json

object

Everything the lyric reader draws for one track: the words, and the furniture round them.

one of
option 1 object

The words, as numbered lines.

language string | null

As detected from the text.

timed boolean required

Whether any line carries a time, so the reader can follow the deck.

romanization object | null

Present when the lyric is in a script that is romanized; each line then carries roman.

language string | null

The language it was romanized as.

indic string required

readable or iso, from the lyrics_indic_style preference.

cyrillic string required

readable or iso, from the lyrics_cyrillic_style preference.

macrons boolean required

Japanese long vowels with macrons, from the lyrics_macrons preference.

from_companion boolean required

Made from the original-script companion rather than the words shown.

kanji boolean required

Whether this build reads kanji and hanzi. Without it (a build with no default features) kana is romanized and ideographs are left as written.

companion object | null

An LRCLIB record kept beside these words in their original script, which romanization is made from while it lines up.

lrclib_id integer | null · int64
language string | null
lines_up boolean required

Same line count as the words. When false it is held but not used.

lines array required

Numbered including blanks. A stanza break is a line, because a note refers to a line by its index and skipping empties would renumber every line after one.

each item
object

One numbered line.

n integer required

1-based, blanks included.

at number | null · double

Seconds into the track, when the lyric is timed.

text string required

Empty for a stanza break, which is a real line.

roman object | null

The line in Latin letters, as words and parts (one Hangul block, one Japanese or Chinese token, one Indic word each). Absent where the line needs none — English, a stanza break — or the lyric is not romanized.

text string required

The whole line as plain text.

words array required
each item
object

A word: parts written together, words separated by a space.

parts array required
each item
object

One unit drawn under its original in the interlinear view.

Deeper structure omitted. The spec is the full reference.

syl boolean

The parts are sung syllables (Korean), so the reader marks the boundaries between them.

pin object | null

The liner note pinned to this line, if any.

note_id integer · int64 required
body_md string required
excerpt string required

The first 200 characters, as text.

visibility string required
updated_at integer · int64 required
quoted integer required

How many notes quote this line. Zero is sent, never omitted.

plain string | null

The stored text, for correcting it by hand.

synced string | null

The stored timed text, [mm:ss.xx] words per line.

edited boolean required

Corrected by hand, and therefore never overwritten by a lookup.

chosen boolean required

An LRCLIB record picked from Other versions — likewise never overwritten by a lookup or a library poll, but still LRCLIB's words.

lrclib_id integer | null · int64

The LRCLIB record these words are, when they are one.

source string | null

Where the words came from — your library, LRCLIB, or you. Shown wherever the words are, because they are not Tapedeck's.

option 2 object

A track with no words — an answer, not a gap.

instrumental boolean required

Always true.

lines array required

Always empty.

each item
object

One numbered line.

n integer required

1-based, blanks included.

at number | null · double

Seconds into the track, when the lyric is timed.

text string required

Empty for a stanza break, which is a real line.

roman object | null

The line in Latin letters, as words and parts (one Hangul block, one Japanese or Chinese token, one Indic word each). Absent where the line needs none — English, a stanza break — or the lyric is not romanized.

text string required

The whole line as plain text.

words array required
each item
object

A word: parts written together, words separated by a space.

parts array required
each item
object

One unit drawn under its original in the interlinear view.

Deeper structure omitted. The spec is the full reference.

syl boolean

The parts are sung syllables (Korean), so the reader marks the boundaries between them.

pin object | null

The liner note pinned to this line, if any.

note_id integer · int64 required
body_md string required
excerpt string required

The first 200 characters, as text.

visibility string required
updated_at integer · int64 required
quoted integer required

How many notes quote this line. Zero is sent, never omitted.

option 3 object

Nothing held for this track.

lines array required

Always empty.

each item
object

One numbered line.

n integer required

1-based, blanks included.

at number | null · double

Seconds into the track, when the lyric is timed.

text string required

Empty for a stanza break, which is a real line.

roman object | null

The line in Latin letters, as words and parts (one Hangul block, one Japanese or Chinese token, one Indic word each). Absent where the line needs none — English, a stanza break — or the lyric is not romanized.

text string required

The whole line as plain text.

words array required
each item
object

A word: parts written together, words separated by a space.

parts array required
each item
object

One unit drawn under its original in the interlinear view.

Deeper structure omitted. The spec is the full reference.

syl boolean

The parts are sung syllables (Korean), so the reader marks the boundaries between them.

pin object | null

The liner note pinned to this line, if any.

note_id integer · int64 required
body_md string required
excerpt string required

The first 200 characters, as text.

visibility string required
updated_at integer · int64 required
quoted integer required

How many notes quote this line. Zero is sent, never omitted.

artist string required
title string required
album string | null

The record the tracklist is drawn from — as asked for, or else the one the track is filed under in your history.

plays integer · int64 required

Your plays of this track.

tracklist array required

The record's tracks, empty with no record.

each item
object
title string required
plays integer · int64 required
duration integer | null · int64

Seconds.

track_number integer | null · int64
lyrics string | null

words or instrumental; null for a track nobody has asked about, which is a different thing from one that has no words.

PUT /api/v1/lyrics #
Session

Correct the words by hand.

Scope: session only.

A value you supplied is never overwritten by a lookup — the rule the shelf's running times already follow, and what settles the collision between this and "newest fetch wins": between two fetches the newer one wins, and between a fetch and something a person typed, the person does. The row is marked as corrected and the backfill will not write over it.

Instance-wide rather than per user, like everything else in this cache: these are one track's words, not one person's opinion of them.

The response reports the line count before and after, and renumbered when they differ. Every reference already written is an index, so a correction that adds or removes a line moves every quote after it onto different words — silently, because an index cannot be wrong, only pointed somewhere else. It is reported rather than refused: the correction is usually the point, and the alternative is a lyric that stays wrong for ever.

Request body required

application/json

object
artist string required
title string required
plain string | null

The words, plain. Absent clears them.

synced string | null

The timed form, [mm:ss.xx] words per line.

Responses

200

Saved.

application/json

object

A hand correction, stored.

status string required

Always saved.

language string | null
lines_before integer required
lines_after integer required
renumbered boolean required

The line count changed, so every [[line:…]] quote past the change now points at different words. Say so.

400

No artist, no title, or no words.

application/json

object

Every error body in the API has this shape.

code integer · int32 required

Mirrors the HTTP status.

error string required

Human-readable. Not a stable identifier — do not branch on it.

POST /api/v1/lyrics/library #
Token writeor Session

Words a player found in its own files.

Scope: write.

Not a correction. PUT /api/v1/lyrics calls set_words, which sets edited and stamps the source as You — a claim only a person typing gets to make, and the flag that outranks every later fetch. A client reporting what a file contains is not correcting anything, so this goes through the library path instead: it refuses to write over an edited row, re-reads the language from the new words, and upserts, so a repeat send is harmless.

Not POST /api/v1/lyrics/fetch either, which spends a shared politeness budget at LRCLIB. This is offering words, not asking for them.

Sends nothing to any third party, and the words never leave the instance — not in a backup, not in an export, not to a patched deck.

Request body required

application/json

object

Words a player found in its own files, offered by the player.

Deliberately not PUT /api/v1/lyrics, which is the correction path: that one calls set_words, which sets edited and stamps the source as You. Typing a line in is a claim only a person gets to make, and a client reporting what a file contains is not correcting anything — so it must not be able to mint the flag that outranks every later fetch.

Nor additional_info on a submission: a lyric is a few KB on every play of a track already held, and ingest stays about the listening.

artist string required
title string required
album string | null

Advisory. Not used to match — track_key is artist and title — and kept out of the store for the same reason.

plain string | null
synced string | null
source string | null

Whose words these are, and required.

The reader prints "Words via X", and that sentence is the entire reason this route exists apart from the LRCLIB one: from your own files and from a lyrics service are different statements about whose text somebody is reading. A client that will not say who it is should not get to write provenance, and inventing one here would be the placeholder User-Agent mistake in a new place.

Typed Option and required in the handler, not by serde. A missing required field is rejected by axum's Json extractor with a 422 before any of this runs — so the client is handed a deserialiser's sentence about a field name instead of the reason, which is the trap additional_info already documents. The requirement is unchanged; only the answer is legible.

Responses

200

Stored, or left alone because the row holds a correction.

application/json

object

What became of words a player offered.

status string required

saved, or kept when the words held were corrected by hand or picked from Other versions — either outranks a file's own tags, so those were left alone.

why string | null

Why they were kept; null when saved.

language string | null

The language of the words now held.

lines integer required

Lines in the words now held.

400

A blank artist, title or source, or no words.

application/json

object

Every error body in the API has this shape.

code integer · int32 required

Mirrors the HTTP status.

error string required

Human-readable. Not a stable identifier — do not branch on it.

401

No valid session cookie or token. Also returned when a token is presented to a session-only endpoint — the endpoint does not accept tokens at all, so the scope is irrelevant.

application/json

object

Every error body in the API has this shape.

code integer · int32 required

Mirrors the HTTP status.

error string required

Human-readable. Not a stable identifier — do not branch on it.

{
  "code": 401,
  "error": "Authentication required. Log in to access this endpoint."
}
GET /api/v1/lyrics/live #
Token reador Session

The words for whatever is on the deck.

Scope: read.

The reader's whole state in one request, so the lyric theatre stops being addressed by URL. GET /api/v1/lyrics names a track, which is right for a [[line:...]] chip and wrong for reading along: the words stayed on whichever song the address named, so the next track left them behind and the only way out was editing the query string.

The body is a LyricDoc with the playhead beside it, so a cold open lands on the right line without waiting for a now-playing poll. Nothing playing is { "playing": false } and a normal answer, not an error.

Ask it once per track, not once per poll. The document carries the tracklist and every pin on the track; a client should watch GET /api/v1/now-playing (which it is already polling) and re-ask this only when the track changes.

Responses

200

The deck's track and its words, or nothing playing.

application/json

The words for whatever is on the deck, or that nothing is.

one of
option 1 object

Nothing is playing — a state, not a failure.

playing boolean required

Always false.

option 2 object

The lyric document for what is playing, plus the playhead.

one of
option 1 object

The words, as numbered lines.

language string | null

As detected from the text.

timed boolean required

Whether any line carries a time, so the reader can follow the deck.

romanization object | null

Present when the lyric is in a script that is romanized; each line then carries roman.

language string | null

The language it was romanized as.

indic string required

readable or iso, from the lyrics_indic_style preference.

cyrillic string required

readable or iso, from the lyrics_cyrillic_style preference.

macrons boolean required

Japanese long vowels with macrons, from the lyrics_macrons preference.

from_companion boolean required

Made from the original-script companion rather than the words shown.

kanji boolean required

Whether this build reads kanji and hanzi. Without it (a build with no default features) kana is romanized and ideographs are left as written.

companion object | null

An LRCLIB record kept beside these words in their original script, which romanization is made from while it lines up.

lrclib_id integer | null · int64
language string | null
lines_up boolean required

Same line count as the words. When false it is held but not used.

lines array required

Numbered including blanks. A stanza break is a line, because a note refers to a line by its index and skipping empties would renumber every line after one.

each item
object

One numbered line.

n integer required

1-based, blanks included.

at number | null · double

Seconds into the track, when the lyric is timed.

text string required

Empty for a stanza break, which is a real line.

roman object | null

The line in Latin letters, as words and parts (one Hangul block, one Japanese or Chinese token, one Indic word each). Absent where the line needs none — English, a stanza break — or the lyric is not romanized.

text string required

The whole line as plain text.

words array required
each item
object

A word: parts written together, words separated by a space.

parts array required

Deeper structure omitted. The spec is the full reference.

syl boolean

The parts are sung syllables (Korean), so the reader marks the boundaries between them.

Deeper structure omitted. The spec is the full reference.

pin object | null

The liner note pinned to this line, if any.

note_id integer · int64 required
body_md string required
excerpt string required

The first 200 characters, as text.

visibility string required
updated_at integer · int64 required
quoted integer required

How many notes quote this line. Zero is sent, never omitted.

plain string | null

The stored text, for correcting it by hand.

synced string | null

The stored timed text, [mm:ss.xx] words per line.

edited boolean required

Corrected by hand, and therefore never overwritten by a lookup.

chosen boolean required

An LRCLIB record picked from Other versions — likewise never overwritten by a lookup or a library poll, but still LRCLIB's words.

lrclib_id integer | null · int64

The LRCLIB record these words are, when they are one.

source string | null

Where the words came from — your library, LRCLIB, or you. Shown wherever the words are, because they are not Tapedeck's.

option 2 object

A track with no words — an answer, not a gap.

instrumental boolean required

Always true.

lines array required

Always empty.

each item
object

One numbered line.

n integer required

1-based, blanks included.

at number | null · double

Seconds into the track, when the lyric is timed.

text string required

Empty for a stanza break, which is a real line.

roman object | null

The line in Latin letters, as words and parts (one Hangul block, one Japanese or Chinese token, one Indic word each). Absent where the line needs none — English, a stanza break — or the lyric is not romanized.

text string required

The whole line as plain text.

words array required
each item
object

A word: parts written together, words separated by a space.

parts array required

Deeper structure omitted. The spec is the full reference.

syl boolean

The parts are sung syllables (Korean), so the reader marks the boundaries between them.

Deeper structure omitted. The spec is the full reference.

pin object | null

The liner note pinned to this line, if any.

note_id integer · int64 required
body_md string required
excerpt string required

The first 200 characters, as text.

visibility string required
updated_at integer · int64 required
quoted integer required

How many notes quote this line. Zero is sent, never omitted.

option 3 object

Nothing held for this track.

lines array required

Always empty.

each item
object

One numbered line.

n integer required

1-based, blanks included.

at number | null · double

Seconds into the track, when the lyric is timed.

text string required

Empty for a stanza break, which is a real line.

roman object | null

The line in Latin letters, as words and parts (one Hangul block, one Japanese or Chinese token, one Indic word each). Absent where the line needs none — English, a stanza break — or the lyric is not romanized.

text string required

The whole line as plain text.

words array required
each item
object

A word: parts written together, words separated by a space.

parts array required

Deeper structure omitted. The spec is the full reference.

syl boolean

The parts are sung syllables (Korean), so the reader marks the boundaries between them.

Deeper structure omitted. The spec is the full reference.

pin object | null

The liner note pinned to this line, if any.

note_id integer · int64 required
body_md string required
excerpt string required

The first 200 characters, as text.

visibility string required
updated_at integer · int64 required
quoted integer required

How many notes quote this line. Zero is sent, never omitted.

artist string required
title string required
album string | null

The record the tracklist is drawn from — as asked for, or else the one the track is filed under in your history.

plays integer · int64 required

Your plays of this track.

tracklist array required

The record's tracks, empty with no record.

each item
object
title string required
plays integer · int64 required
duration integer | null · int64

Seconds.

track_number integer | null · int64
lyrics string | null

words or instrumental; null for a track nobody has asked about, which is a different thing from one that has no words.

playing boolean required

Always true.

position integer · int64 required

Seconds into the track.

position_ms integer · int64 required

The same, in milliseconds.

position_known boolean required

Whether position is a measurement. Do not drive a highlight from a guess.

paused boolean required
duration integer | null · int64

Seconds.

POST /api/v1/lyrics/fetch #
Session

Look for one track's words now.

Session only. A token is refused with 401 and its scopes never enter into it: this spends a shared politeness budget at a free service and writes an instance-wide cache, which is not something a scrobble client holding read has any business doing.

The backfill runs at a few tracks a minute, most-played first, which is the right pace for a queue nobody is watching and no use for the track somebody is looking at. This is the button behind that, and it resolves the track exactly as the backfill would: the user's own library first, then LRCLIB, with cues winning.

A deliberate press is not a page load, which is why this may ask LRCLIB where GET /api/v1/lyrics may not. It bypasses the 30-day miss tombstone — LRCLIB fills its own gaps, so "nobody had this a fortnight ago" is exactly the answer worth re-asking — but it will not displace words already held: already_held: true says so, and /api/v1/lyrics/matches is the control for disagreeing with them.

A rate limit or an unreachable LRCLIB is 200 with unavailable, not a 5xx. Being asked to wait is not this server failing, and reporting it as "nothing found" would be a claim about the track rather than about the request.

Request body required

application/json

object
artist string required
title string required
album string | null

Narrows the LRCLIB lookup when the caller knows it.

duration integer | null · int64

Likewise — LRCLIB matches on length, and a wrong-length record is the usual reason a well-known song comes back with somebody else's words.

Responses

200

The whole document as it now stands, so the caller can replace what it is showing — or unavailable with a why.

application/json

A lookup's outcome: the whole lyric document, or why nobody could be asked.

one of
option 1 object

LRCLIB could not be asked — rate limited or unreachable. Not "there are no words": nothing was learned about the track.

unavailable boolean required

Always true.

why string required
option 2 object

The document, as the reader should now show it.

one of
option 1 object

The words, as numbered lines.

language string | null

As detected from the text.

timed boolean required

Whether any line carries a time, so the reader can follow the deck.

romanization object | null

Present when the lyric is in a script that is romanized; each line then carries roman.

language string | null

The language it was romanized as.

indic string required

readable or iso, from the lyrics_indic_style preference.

cyrillic string required

readable or iso, from the lyrics_cyrillic_style preference.

macrons boolean required

Japanese long vowels with macrons, from the lyrics_macrons preference.

from_companion boolean required

Made from the original-script companion rather than the words shown.

kanji boolean required

Whether this build reads kanji and hanzi. Without it (a build with no default features) kana is romanized and ideographs are left as written.

companion object | null

An LRCLIB record kept beside these words in their original script, which romanization is made from while it lines up.

lrclib_id integer | null · int64
language string | null
lines_up boolean required

Same line count as the words. When false it is held but not used.

lines array required

Numbered including blanks. A stanza break is a line, because a note refers to a line by its index and skipping empties would renumber every line after one.

each item
object

One numbered line.

n integer required

1-based, blanks included.

at number | null · double

Seconds into the track, when the lyric is timed.

text string required

Empty for a stanza break, which is a real line.

roman object | null

The line in Latin letters, as words and parts (one Hangul block, one Japanese or Chinese token, one Indic word each). Absent where the line needs none — English, a stanza break — or the lyric is not romanized.

text string required

The whole line as plain text.

words array required
each item
object

A word: parts written together, words separated by a space.

parts array required

Deeper structure omitted. The spec is the full reference.

syl boolean

The parts are sung syllables (Korean), so the reader marks the boundaries between them.

Deeper structure omitted. The spec is the full reference.

pin object | null

The liner note pinned to this line, if any.

note_id integer · int64 required
body_md string required
excerpt string required

The first 200 characters, as text.

visibility string required
updated_at integer · int64 required
quoted integer required

How many notes quote this line. Zero is sent, never omitted.

plain string | null

The stored text, for correcting it by hand.

synced string | null

The stored timed text, [mm:ss.xx] words per line.

edited boolean required

Corrected by hand, and therefore never overwritten by a lookup.

chosen boolean required

An LRCLIB record picked from Other versions — likewise never overwritten by a lookup or a library poll, but still LRCLIB's words.

lrclib_id integer | null · int64

The LRCLIB record these words are, when they are one.

source string | null

Where the words came from — your library, LRCLIB, or you. Shown wherever the words are, because they are not Tapedeck's.

option 2 object

A track with no words — an answer, not a gap.

instrumental boolean required

Always true.

lines array required

Always empty.

each item
object

One numbered line.

n integer required

1-based, blanks included.

at number | null · double

Seconds into the track, when the lyric is timed.

text string required

Empty for a stanza break, which is a real line.

roman object | null

The line in Latin letters, as words and parts (one Hangul block, one Japanese or Chinese token, one Indic word each). Absent where the line needs none — English, a stanza break — or the lyric is not romanized.

text string required

The whole line as plain text.

words array required
each item
object

A word: parts written together, words separated by a space.

parts array required

Deeper structure omitted. The spec is the full reference.

syl boolean

The parts are sung syllables (Korean), so the reader marks the boundaries between them.

Deeper structure omitted. The spec is the full reference.

pin object | null

The liner note pinned to this line, if any.

note_id integer · int64 required
body_md string required
excerpt string required

The first 200 characters, as text.

visibility string required
updated_at integer · int64 required
quoted integer required

How many notes quote this line. Zero is sent, never omitted.

option 3 object

Nothing held for this track.

lines array required

Always empty.

each item
object

One numbered line.

n integer required

1-based, blanks included.

at number | null · double

Seconds into the track, when the lyric is timed.

text string required

Empty for a stanza break, which is a real line.

roman object | null

The line in Latin letters, as words and parts (one Hangul block, one Japanese or Chinese token, one Indic word each). Absent where the line needs none — English, a stanza break — or the lyric is not romanized.

text string required

The whole line as plain text.

words array required
each item
object

A word: parts written together, words separated by a space.

parts array required

Deeper structure omitted. The spec is the full reference.

syl boolean

The parts are sung syllables (Korean), so the reader marks the boundaries between them.

Deeper structure omitted. The spec is the full reference.

pin object | null

The liner note pinned to this line, if any.

note_id integer · int64 required
body_md string required
excerpt string required

The first 200 characters, as text.

visibility string required
updated_at integer · int64 required
quoted integer required

How many notes quote this line. Zero is sent, never omitted.

artist string required
title string required
album string | null

The record the tracklist is drawn from — as asked for, or else the one the track is filed under in your history.

plays integer · int64 required

Your plays of this track.

tracklist array required

The record's tracks, empty with no record.

each item
object
title string required
plays integer · int64 required
duration integer | null · int64

Seconds.

track_number integer | null · int64
lyrics string | null

words or instrumental; null for a track nobody has asked about, which is a different thing from one that has no words.

already_held boolean required

The words were already held, so nothing was fetched.

400

An artist or a title that is blank.

application/json

object

Every error body in the API has this shape.

code integer · int32 required

Mirrors the HTTP status.

error string required

Human-readable. Not a stable identifier — do not branch on it.

422

The body is missing artist or title outright.

GET /api/v1/lyrics/matches #
Token reador Session

The other records LRCLIB holds for a track.

Session or a read token.

Not a version history. LRCLIB has none — /api/get returns one record and nothing behind it. These are different records for the same song, from /api/search: other uploads, other pressings, a live take filed under the same name. Picking a better one is how a wrong match is fixed without typing the words out.

Records with no words are omitted. The whole gesture is "these are the wrong words, give me the other ones", which an instrumental cannot answer.

Adopt one with POST /api/v1/lyrics/adopt, by its id. The pick survives every later fetch and library poll, is credited to LRCLIB, and the response reports renumbered — which matters here more than anywhere: a [[line:...]] reference is an index, so a different record re-points every quote already written.

search_artist and search_title search under other names than the track's own, for tags LRCLIB files differently. held marks the record already stored for the track.

This reaches the network, so it belongs on a press rather than a page load. A rate limit or an unreachable LRCLIB comes back 200 with unavailable: true and a reason rather than a 5xx: the upstream asking us to wait is not this server failing, and the distinction is what stops a client reporting "no other matches" when it never managed to ask.

Parameters

artist query required

The track, as it is filed here.

string
title query required
string
search_artist query

Search LRCLIB under a different artist than the track's — for tags that name it differently (a romanised name, a "feat." credit).

string
search_title query

Likewise for the title.

string

Responses

200

OK.

application/json

object

The records LRCLIB holds for a track.

matches array required
each item
object

One LRCLIB record for the track.

id integer | null · int64

LRCLIB's id — what POST /api/v1/lyrics/adopt takes.

title string | null
artist string | null
album string | null

The release the record was filed under — usually what tells two uploads of one song apart.

duration integer | null · int64

Seconds.

synced boolean required

Timed — a timed lyric follows the deck, a plain one cannot.

lines integer required

Lines, blanks included.

language string | null

The language read off the record's script, null for Latin text. The question this list most often answers is "is there one in the original script", which a romanised upload and a native one look identical on every other field.

held boolean required

This is the record already held.

plain string | null
synced_text string | null
unavailable boolean | null

Present, and true, when LRCLIB could not be asked. matches is then empty and says nothing about the track.

why string | null

Why, when unavailable.

400

Missing artist or title.

application/json

object

Every error body in the API has this shape.

code integer · int32 required

Mirrors the HTTP status.

error string required

Human-readable. Not a stable identifier — do not branch on it.

POST /api/v1/lyrics/adopt #
Session

Hold an LRCLIB record picked from *Other versions*.

Session only. It reaches LRCLIB and writes the instance-wide cache, which a token is not for.

The server fetches the record by id itself. The words are credited to LRCLIB, and the pick is kept: no later fetch and no library poll replaces it. It replaces a hand correction, since choosing is as deliberate as typing and the later act wins; Fix the words afterwards is a correction again.

Reports the line count before and after, and renumbered when they differ: a [[line:…]] reference is an index, so a record with a different count re-points every quote past the change.

A rate limit or an unreachable LRCLIB is 200 with unavailable — nothing was changed and nothing was learned about the record.

Request body required

application/json

object

An LRCLIB record to hold for a track.

artist string required

The track, as it is filed here — not necessarily the record's own names.

title string required
id integer · int64 required

The LRCLIB record, from GET /api/v1/lyrics/matches.

original_script boolean

Keep the record beside the words held, as their original script, rather than replacing them. For words held in Latin letters (a lyric tagged romanised in your own files): they stay what a note quotes, and romanization is made from this record. Refused unless it lines up.

Responses

200

Held — or unavailable with a why.

application/json

A picked record, held — or why LRCLIB could not be asked.

one of
option 1 object

LRCLIB could not be asked. Nothing was changed.

unavailable boolean required

Always true.

why string required
option 2 object

Kept beside the words as their original script (original_script).

status string required

Always companion.

language string | null
lines integer required
option 3 object

Held.

status string required

Always adopted.

language string | null
lines_before integer required
lines_after integer required
renumbered boolean required

The line count changed, so every [[line:…]] quote past the change now points at different words. Say so.

400

A blank artist or title, a record with no words — or, keeping it as the original script, one that does not line up with the words held.

application/json

object

Every error body in the API has this shape.

code integer · int32 required

Mirrors the HTTP status.

error string required

Human-readable. Not a stable identifier — do not branch on it.

404

LRCLIB has no record with that id.

application/json

object

Every error body in the API has this shape.

code integer · int32 required

Mirrors the HTTP status.

error string required

Human-readable. Not a stable identifier — do not branch on it.

422

The body is missing a field outright.

DELETE /api/v1/lyrics/companion #
Session

Forget the original-script companion kept beside a track's words.

Session only. The words are untouched; romanization goes back to being made from them (which, for words held in Latin letters, means none).

Parameters

artist query required
string
title query required
string
album query

Which record to draw the tracklist from.

Optional and resolved from the history when it is absent, because the caller is usually a note or a history row that knows the track and not the record it was filed under. Passed explicitly it wins, since a track on three compilations has three honest answers and only the caller knows which one is being read.

string

Responses

200

Forgotten, or there was none.

application/json

object

An original-script companion, forgotten.

status string required

Always cleared.

400

Missing artist or title.

application/json

object

Every error body in the API has this shape.

code integer · int32 required

Mirrors the HTTP status.

error string required

Human-readable. Not a stable identifier — do not branch on it.

GET /api/v1/lyrics/keys #
Token reador Session

Every track this instance holds words for.

Scope: read.

One request for the whole set, exactly the shape GET /api/v1/loves/keys has and for the same reason: a history page wants to know which of fifty rows has something to read, and fifty questions is not the way to ask.

A key is <artist>|<title>, both trimmed and lowercased — the same fold loveKey uses for its artist half. The browser's derivation and this one must stay in step, or "Read the words" quietly stops appearing on rows that have lyrics and nothing errors.

Only tracks with words. An instrumental is a real answer and a finished lookup, but there is nothing to open a reader on.

Not scoped to the caller, and it cannot be: the cache is one copy of one track's words for the whole instance, keyed by the track rather than by who played it.

Responses

200

OK. An instance with no lyrics cache answers an empty list rather than failing.

application/json

object

Every track this instance holds words for.

keys array required

<artist key>|<title> for each: the artist folded the way artist pages fold names (case, accents, spacing), the title trimmed and lowercased. Derive a row's key the same way.

each item
string
GET /api/v1/reports #
Session or Token read

Period reports — a feed of week / month / year cards, newest first.

Scope: read (since v0.41).

Reads the history once and folds it in Rust. A card carries a dozen aggregates and every one is bucketed in the caller's own timezone, which SQL here cannot do — a year of monthly cards would otherwise be hundreds of round trips.

Weeks are ISO (Monday-start), deliberately not the caller's week-start preference: that setting shapes the dashboard counter and the heatmap rows, whereas a report is a named object and its boundary has to stay put, or last month's report changes shape when the preference does.

avg_daily divides by calendar days — a finished period by its full length, one still running by the days it has actually had. Dividing by days-with-listens would report the rate of your busiest fortnight as the month's average.

Two things deliberately absent. There is no percentile against other users ("you out-listened 88% of listeners"): that needs other people's listening, and on a private instance it would leak how much the rest of the household plays. And crush is omitted for the oldest period, where every artist is new by construction and it would just be the top artist relabelled.

Parameters

unit query

week, month (default) or year.

string
limit query

How many periods to return, newest first. 12 by default, at most 60.

integer
offset query

Periods to skip, counting back from the newest. The stepper on the Reports page walks this one period at a time. Costs nothing extra — the whole history is folded on every call regardless.

integer

Responses

200

OK.

application/json

object

A feed of period cards, newest first.

unit string required

week, month or year.

timezone string required

The IANA zone the buckets were cut in.

periods array required
each item
object

One week, month or year.

key string required

2026-W31, 2026-08, 2026.

label string required
start integer · int64 required

Unix seconds — the first listen in the period.

end integer · int64 required

Unix seconds — the last listen in the period.

plays integer · int64 required
hours number · double required
avg_daily integer · int64 required

Plays per calendar day — a finished period by its full length, one still running by the days it has actually had.

artists integer required
albums integer required
tracks integer required
new_artists integer required

Artists with no earlier listen anywhere in the history.

top_artist object | null

Never "Various Artists", which is a filing convention, not an artist.

name string required

The latest spelling actually submitted.

plays integer · int64 required
hours number · double required
landscape_url string | null

A wide image, when you chose one for this artist. Absent otherwise — nothing Tapedeck can reach supplies one.

top_album object | null
name string required
artist string required
plays integer · int64 required
top_track object | null
title string required
artist string required
artist_credit string | null

Everyone credited, "; "-joined and primary first, when there is more than one.

plays integer · int64 required
clock array required

24 counts, local hours.

each item
integer · int64
sub array required

One level finer than the period — days across a week, weeks across a month, months across a year.

each item
integer · int64
sub_labels array required
each item
string
genres array required

The six biggest genres. Shares of tag mentions, not of listens.

each item
object
name string required
pct integer · int64 required

A whole percentage of tag mentions.

genre_bands object required

The period's three biggest genres by name, fixed across every sub-bucket, plus other as the remainder. Drawn as stacked bands by the year chapter. A sub-bucket with no tags at all is all zeroes rather than 100% other — an empty month is an absence, not a genre.

Shares of tag mentions, like genres.

names array required

At most three.

each item
string
shares array required

One row per sub-bucket; each row is the named shares then other.

each item
array
each item
number · double
rank integer required

Where this period sits among your own periods by plays, 1 being the busiest. This is what fills the slot the design gave to a cross-user percentile — there is no such thing here: it needs other people's listening, and on a private instance it would leak how much the rest of the household plays.

rank_of integer required

How many periods rank is out of.

colour string | null

Play-weighted blend of the period's genre colours, in linear light. Null until the genre map is fetched.

on_repeat array required

The heaviest single days of single tracks — three plays or more.

each item
object
title string required
artist string required
artist_credit string | null

Everyone credited, "; "-joined and primary first, when there is more than one.

plays integer · int64 required
crush object | null

Most-played artist never played before, with at least five plays. Null for the oldest period, where every artist is new by construction and it would just be the top artist relabelled.

name string required

The first spelling it arrived under.

plays integer · int64 required
since integer · int64 required

Unix seconds of the first listen.

shelf object required

Sides played off the shelf.

sides integer · int64 required
rows array required

The five most-played sides.

each item
object
title string required
artist string required
side string required
spins integer · int64 required
top_chain string | null

The chain most listens went through.

gear object required

What the period was listened through. unattributed and no_duration are stated rather than folded away: on most histories the first is nearly everything, and the hours are a floor without the second.

chains array required
each item
object
name string required
icon string | null
plays integer · int64 required
hours number · double required
items array required

The eight pieces of gear with the most hours, each counted once per chain even when a chain names it twice.

each item
object
name string required
type string required

The component type, lowercased — dac, amp, transducer…

plays integer · int64 required
hours number · double required
unattributed integer · int64 required

Listens with no chain at all.

no_duration integer · int64 required

Chained listens whose source reported no length.

company object required

Listens marked as heard with somebody. company is null on everything nobody has tagged, so of_plays travels as the denominator — never present a bare share, and never read the complement as "alone".

marked_plays integer · int64 required
marked_hours number · double required
of_plays integer · int64 required
people array required

The eight people heard with most.

each item
object
name string required
plays integer · int64 required
fingerprint object required

Five ratios between 0 and 1, and the same five for you, usually — every one answerable from any history, and none of them a comparison against another person. The baseline is the mean of your own periods, not one shape over the whole history: variety shrinks as plays grow and discovery is pinned at 1.0 over a whole history, so a whole-history baseline would report every period as more varied and less exploratory than usual.

axes array required

Variety, Repeat, Discovery, Spread, Runs.

each item
string
you array required
each item
number · double
usual array required
each item
number · double
usual_periods integer required

How many periods the baseline rests on. One is not a habit — a radar comparing a month against itself draws two identical shapes and means nothing by it, so decline to draw the baseline below two.

milestones array required

Sentences worth a line of their own — "your 10,000th listen".

each item
string
prev object | null

The period before, for deltas. Null for the oldest.

label string required
plays integer · int64 required
hours number · double required
avg_daily integer · int64 required
artists integer required
albums integer required
tracks integer required
sub array required
each item
integer · int64
offset integer required

Where this page sits, counting back from the newest.

total_periods integer required

How many periods exist at this bucket size — what tells a stepper where the ends are.

capped boolean | null

The scan hit the analytics row cap, so the oldest periods are partial and must not be presented as final. Absent with no listening at all.

401

No valid session cookie or token. Also returned when a token is presented to a session-only endpoint — the endpoint does not accept tokens at all, so the scope is irrelevant.

application/json

object

Every error body in the API has this shape.

code integer · int32 required

Mirrors the HTTP status.

error string required

Human-readable. Not a stable identifier — do not branch on it.

{
  "code": 401,
  "error": "Authentication required. Log in to access this endpoint."
}
403

Authenticated, but not permitted. Either the token lacks the required scope, or the endpoint needs the admin role. Deliberately not a 401 — re-authenticating will not help.

application/json

object

Every error body in the API has this shape.

code integer · int32 required

Mirrors the HTTP status.

error string required

Human-readable. Not a stable identifier — do not branch on it.

{
  "code": 403,
  "error": "This token does not have the 'write' scope"
}
GET /api/v1/reports/graphs #
Session or Token read

The graphs for one report period.

Scope: read (since v0.130). The Statistics graphs (see GET /api/v1/stats/graphs) over one week, month or year, plus who topped each part of it. Artists are everyone credited.

Parameters

unit query required

week, month or year — the bucket the key is from.

string
key query required

The period, as a report's key names it: 2026-W31, 2026-08 or 2026.

string

Responses

200

OK.

application/json

object

The graphs drawn under one report chapter.

unit string required

week, month or year.

key string required
timezone string required

The IANA zone the period and its days are bucketed in.

graphs object required

The Statistics graphs over this period's calendar window — up to today while it is still running. The page draws the ones that suit the period's size; all of them are here.

range string required

The range asked for: week, month, last30, year or all.

timezone string required

The IANA zone every day below is bucketed in.

capped boolean required

True when the history was longer than this server reads in one pass (scaled to its memory). The oldest listens are the ones left out.

start_day string | null

First local day of the axis, YYYY-MM-DD. Absent when the range is empty. Every daily array below starts here, one entry per day.

daily array required

Listens per local day, from start_day to today, including days with none.

each item
integer · int64
volume object required
plays integer · int64 required

Listens in the range.

active_days integer · int64 required

Days in the range with at least one listen.

median_active_day number · double required

Median listens on a day you listened at all. Zero-listen days are left out on purpose: they would drag the median of a sparse history to 0.

peak object | null

The busiest day in the range.

day string required

YYYY-MM-DD, local.

plays integer · int64 required
waves array required

The most-credited artists in the range, with their own daily counts on the same axis as daily.

each item
object
name string required
plays integer · int64 required

Credited plays in the range.

daily array required

Credited plays per local day, aligned with StatsGraphs::daily.

each item
integer · int64
long_tail object required
counts array required

Credited plays per artist, largest first. The curve is their running sum over credits.

each item
integer · int64
credits integer · int64 required

The sum of counts: artist credits, not listens — a listen with two artists credited counts once for each.

once integer · int64 required

Artists heard exactly once in the range.

hundred_plus integer · int64 required

Artists heard 100 times or more in the range.

half integer · int64 required

How many of the top artists it takes to reach half of credits.

eighty integer · int64 required

How many of the top artists it takes to reach 80% of credits.

sessions object required
total integer · int64 required

Sessions in the range. A gap longer than gap_minutes starts a new one.

gap_minutes integer · int64 required
lengths array required

Sessions by how many listens they held, in fixed buckets.

each item
object
label string required

1, 2, 3–4, 5–9, 10–19, 20–49, 50–99 or 100+.

sessions integer · int64 required
devotion object required

How much of each session went to its most-played artist.

Measured over sessions of at least min_listens, and over the primary artist of each listen — fanning credits out here would let one session's shares add up to more than everything played in it.

min_listens integer · int64 required
devoted integer · int64 required

One artist took 80% or more of the session.

mixed integer · int64 required

The top artist took 40–80%.

scattered integer · int64 required

No artist took as much as 40%.

first_listens array required

The range's most-credited artists, ordered by when you first heard them — across the whole history, not the range.

each item
object
name string required
plays integer · int64 required

Credited plays in the range.

first integer · int64 required

First listen ever, unix seconds — not ranged.

last integer · int64 required

Most recent listen, unix seconds — not ranged.

loyalty number · double required

0–100. High is steady, recurring listening; low is bursts.

habits array required

Daily habit or burst: how each artist's listening is spread over time. Only artists with five or more plays on at least two different days.

each item
object
name string required
plays integer · int64 required

Credited plays in the range.

active_days integer · int64 required

Days in the range this artist was played.

span_days integer · int64 required

Days from their first to their last listen in the range, inclusive.

return_rate number · double required

active_days / span_days: how often they come back. 1 = every day.

top_day_share number · double required

Share of their plays on their single biggest day. 1 = all on one day.

top_day string required

That biggest day, YYYY-MM-DD.

loyalty number · double required

0–100. High is steady, recurring listening; low is bursts.

albums array required

How each top artist's plays split across their records.

each item
object
name string required
plays integer · int64 required

Credited plays in the range.

album_count integer · int64 required

Distinct records those plays were on.

albums array required

The most-played records, largest first, at most five.

each item
object
name string required
album_artist string required

Who the record is filed under, which is what opens it.

plays integer · int64 required
rest_plays integer · int64 required

Plays on every other record.

no_album integer · int64 required

Plays whose source named no record at all.

anchors array required

Artists you mostly play one song from, most anchored first.

each item
object
name string required
plays integer · int64 required

Credited plays in the range.

title string required

The one song most of them are.

title_plays integer · int64 required
share number · double required

title_plays / plays.

tracks integer · int64 required

How many different songs of theirs were played at all.

throne array required

Who topped each week of a month, or each month of a year. Empty for a week.

each item
object

Who had the most listens in one part of a report's period: a week of a month, or a month of a year.

start string required

The part's first day, YYYY-MM-DD, local.

label string required

Jan, or 1–7 Aug — clipped to the period, so a month's first week starts on the 1st.

artist string | null

Whoever was credited on the most listens. Absent for a part with none.

plays integer · int64 required

Their credited listens in that part.

listens integer · int64 required

Every listen in that part — the population plays is part of.

400

Not a unit, or not a period key of that unit.

application/json

object

Every error body in the API has this shape.

code integer · int32 required

Mirrors the HTTP status.

error string required

Human-readable. Not a stable identifier — do not branch on it.

401

No valid session cookie or token. Also returned when a token is presented to a session-only endpoint — the endpoint does not accept tokens at all, so the scope is irrelevant.

application/json

object

Every error body in the API has this shape.

code integer · int32 required

Mirrors the HTTP status.

error string required

Human-readable. Not a stable identifier — do not branch on it.

{
  "code": 401,
  "error": "Authentication required. Log in to access this endpoint."
}
403

Authenticated, but not permitted. Either the token lacks the required scope, or the endpoint needs the admin role. Deliberately not a 401 — re-authenticating will not help.

application/json

object

Every error body in the API has this shape.

code integer · int32 required

Mirrors the HTTP status.

error string required

Human-readable. Not a stable identifier — do not branch on it.

{
  "code": 403,
  "error": "This token does not have the 'write' scope"
}
GET /api/v1/reports/image #
Session or Token read

A report chapter as a shareable PNG, rendered on the server.

Scope: read (since v0.96).

Rendered on the server on purpose. A share image is a deliverable rather than a view: a native client asks for one instead of reimplementing a layout, a type scale and a palette that would then be free to drift from the web's. The fonts are embedded in the binary and no artwork is fetched, so the same period produces the same bytes on any host.

It computes nothing. Every figure comes from GET /api/v1/reports with the same unit and offset, so a share cannot disagree with the chapter it was shared from — including the rule that the only comparison on the card is against the caller's own periods.

The card is a composition, not a screenshot of the chapter, and each unit has its own — never one card relabelled, the same reason the app has three chapter components:

  • week — a headline, the by-day bars, the top artist and the track of the week, the counts, the crush. Deliberately no genre split: seven days make a thin one, which is the chapter's own judgement.
  • month — the top artist and record, the counts, the top genres, what was on repeat, the crush. No by-week bars: five columns say less than the ranked genre list beneath them.
  • year — the by-month bars and the genre bands (the three biggest genres tracked by name across the year, everything else folded into other), the artist and record of the year, what was discovered, the crush.

A section that would not fit is left out whole rather than clipped — a PNG has no scrollbar, so a section drawn over the footer would look deliberate. A thin period therefore draws fewer sections rather than empty headings, and a full year gives up its discovery line before it gives up the crush.

Parameters

unit query

week, month (default) or year. Each has its own composition — there is no card that is another card at a different size.

string
offset query

How many periods back from the newest, matching the Reports stepper.

integer
size query

story (default), square or wide.

string
theme query

dark (default) or light. Asked at export time, not inherited — a share lands on somebody else's feed rather than inside the app, so the reader's own theme preference is not the question being answered.

string
format query

png (default) or svg. The SVG is the same document the PNG is rasterised from: smaller, sharp at any size, and something a native client can draw itself. It is not a second renderer — if the two ever disagreed it would be because one of them was not this one.

string

Responses

200

The image. Cache-Control is private: it is one person's listening, and a shared cache must not hold it.

image/png

string · binary

image/svg+xml

string
400

An unsupported unit, size or format.

application/json

object

Every error body in the API has this shape.

code integer · int32 required

Mirrors the HTTP status.

error string required

Human-readable. Not a stable identifier — do not branch on it.

404

No report for that period — an offset past the end of the history, or an instance with nothing in it yet. A real answer, not a failure.

application/json

object

Every error body in the API has this shape.

code integer · int32 required

Mirrors the HTTP status.

error string required

Human-readable. Not a stable identifier — do not branch on it.

GET /api/v1/reports/mixdown #
Session or Token read

A report period as a short animated mixdown.

Scope: read (since v0.131).

The same facts as the chapter and its share image, told one at a time: a few scenes, each a stack of SVG layers that fade, rise and count into place. The server draws every layer — text is already fitted, escaped and set in the embedded fonts' metrics — and a client only moves them.

To play it: draw background, then for the current scene draw each layer's svg inside a group whose transform and opacity come from its tracks at the scene's elapsed milliseconds.

  • A track is a list of {t, v} keys. Before the first key the value is the first key's, after the last the last key's, and between two keys it eases out: a + (b - a) * (1 - (1 - p)^3). An absent track is at rest (opacity 1, offsets 0, scales 1).
  • The group's transform is translate(dx + ox, dy + oy) scale(scale * scale_x, scale * scale_y) translate(-ox, -oy) where (ox, oy) is the layer's origin.
  • A layer with count carries the literal {{n}} in its svg; replace it with the eased value between start_ms and end_ms, rounded and written with thousands separators.
  • In its last fade_out_ms a scene's layers fade out together. The last scene has none and is held.

Pictures. A layer may contain an <image> whose href is the top artist's portrait, the record's cover or the track's: either a web URL or a path on this server (fetch it with the same credentials). Each sits over a lettered tile, so a picture that is absent or fails to load needs no handling — draw the layer as it is.

It computes nothing: every figure comes from GET /api/v1/reports with the same unit and offset. A scene the period has nothing to say in is absent rather than empty, so a thin period is a shorter mixdown.

Parameters

unit query

week, month (default) or year.

string
offset query

How many periods back from the newest, matching the Reports stepper.

integer
theme query

dark (default) or light. Asked for, not inherited, for the same reason the share image asks: the result lands on somebody else's feed.

string

Responses

200

The mixdown.

application/json

object

A mixdown, and whether this server can turn it into a video.

width integer · int32 required
height integer · int32 required
fps integer · int32 required

The video's frame rate. A player may draw more often than this.

unit string required
label string required

The period's own name: "2026", "August 2026", "Week of 17 August".

theme string required
background string required

SVG drawn under every scene and never animated.

scenes array required
each item
object

A few seconds about one fact.

id string required

What the scene is about: intro, volume, shape, artist, record, discovery or outro. A period with nothing to say about one of these has no such scene.

duration_ms integer · int32 required
fade_out_ms integer · int32 required

How long the scene takes to fade into the next one, at its end. Zero for the last scene, which is held.

layers array required

Bottom first.

each item
object

One thing on screen: a piece of SVG and how it moves.

svg string required

SVG elements in mixdown coordinates (no <svg> root). Text is already fitted and escaped; draw it as it is.

origin array required

The point scales are taken about, in mixdown pixels.

each item
number · float
tracks object required

How one layer moves. Every track is optional; an empty one means the property stays at rest (opacity 1, no offset, scale 1).

Before a track's first key the value is the first key's, after its last the last key's, and between two keys it eases out (cubic) from one to the other.

opacity array
each item
object

One point on a track: at t milliseconds into the scene the value is v.

t integer · int32 required

Deeper structure omitted. The spec is the full reference.

v number · float required

Deeper structure omitted. The spec is the full reference.

dx array

Horizontal offset in mixdown pixels.

each item
object

One point on a track: at t milliseconds into the scene the value is v.

t integer · int32 required

Deeper structure omitted. The spec is the full reference.

v number · float required

Deeper structure omitted. The spec is the full reference.

dy array

Vertical offset in mixdown pixels; positive is down.

each item
object

One point on a track: at t milliseconds into the scene the value is v.

t integer · int32 required

Deeper structure omitted. The spec is the full reference.

v number · float required

Deeper structure omitted. The spec is the full reference.

scale array

Uniform scale about the layer's origin.

each item
object

One point on a track: at t milliseconds into the scene the value is v.

t integer · int32 required

Deeper structure omitted. The spec is the full reference.

v number · float required

Deeper structure omitted. The spec is the full reference.

scale_x array

Horizontal scale about the origin, multiplied with scale.

each item
object

One point on a track: at t milliseconds into the scene the value is v.

t integer · int32 required

Deeper structure omitted. The spec is the full reference.

v number · float required

Deeper structure omitted. The spec is the full reference.

scale_y array

Vertical scale about the origin, multiplied with scale.

each item
object

One point on a track: at t milliseconds into the scene the value is v.

t integer · int32 required

Deeper structure omitted. The spec is the full reference.

v number · float required

Deeper structure omitted. The spec is the full reference.

count object | null

Present when svg carries the {{n}} token.

from integer · int64 required
to integer · int64 required
start_ms integer · int32 required
end_ms integer · int32 required
fully_covered boolean required

False when a string that is drawn contains a character the embedded fonts cannot draw. The video may then show boxes for it; a browser, which has its own fonts, usually will not.

video_export boolean required

True when the server has an encoder and POST /api/v1/reports/mixdown/video will work. False is not an error: the mixdown still plays, there is just nothing to download.

400

An unsupported unit.

application/json

object

Every error body in the API has this shape.

code integer · int32 required

Mirrors the HTTP status.

error string required

Human-readable. Not a stable identifier — do not branch on it.

404

No report for that period — an offset past the end of the himixdown, or an instance with nothing in it yet.

application/json

object

Every error body in the API has this shape.

code integer · int32 required

Mirrors the HTTP status.

error string required

Human-readable. Not a stable identifier — do not branch on it.

POST /api/v1/reports/mixdown/video #
Session or Token read

Start making a video of a mixdown.

Scope: read (since v0.131). A POST that needs only read: nothing of yours is written, the result is a temporary file.

Returns at once with a job to poll at GET /api/v1/reports/mixdown/video/{id}. The video is 1080×1920 H.264 at 30 frames a second with no sound, drawn from the same mixdown the GET returns, and is kept for an hour.

Pictures are fetched by the server before the first frame, each with a deadline. One that does not arrive, or is not a PNG, JPEG, GIF or WebP, is left out and its lettered tile shows instead; the export does not fail.

One video is made at a time on the whole server, so queued means somebody else's is being drawn. Each user may have one export in flight.

Parameters

unit query

week, month (default) or year.

string
offset query

How many periods back from the newest, matching the Reports stepper.

integer
theme query

dark (default) or light. Asked for, not inherited, for the same reason the share image asks: the result lands on somebody else's feed.

string

Responses

202

The export was queued.

application/json

object

Where a video export has got to.

id string required
state string required

queued (another render is running), rendering, done or failed.

frames_done integer · int32 required
frames_total integer · int32 required
bytes integer · int64 required

The file's size once state is done, otherwise 0.

error string | null

Why it failed, when it did.

400

An unsupported unit.

application/json

object

Every error body in the API has this shape.

code integer · int32 required

Mirrors the HTTP status.

error string required

Human-readable. Not a stable identifier — do not branch on it.

404

No report for that period.

application/json

object

Every error body in the API has this shape.

code integer · int32 required

Mirrors the HTTP status.

error string required

Human-readable. Not a stable identifier — do not branch on it.

409

You already have a video being made.

application/json

object

Every error body in the API has this shape.

code integer · int32 required

Mirrors the HTTP status.

error string required

Human-readable. Not a stable identifier — do not branch on it.

501

This server has no video encoder (ffmpeg with libx264). The mixdown still plays.

application/json

object

Every error body in the API has this shape.

code integer · int32 required

Mirrors the HTTP status.

error string required

Human-readable. Not a stable identifier — do not branch on it.

GET /api/v1/reports/mixdown/video/{id} #
Session or Token read

How a video export is getting on.

Scope: read (since v0.131).

Parameters

id path required

The export, as POST /api/v1/reports/mixdown/video named it.

string

Responses

200

The export's state.

application/json

object

Where a video export has got to.

id string required
state string required

queued (another render is running), rendering, done or failed.

frames_done integer · int32 required
frames_total integer · int32 required
bytes integer · int64 required

The file's size once state is done, otherwise 0.

error string | null

Why it failed, when it did.

404

No such export. They are kept for an hour, and only their owner can see them.

application/json

object

Every error body in the API has this shape.

code integer · int32 required

Mirrors the HTTP status.

error string required

Human-readable. Not a stable identifier — do not branch on it.

GET /api/v1/reports/mixdown/video/{id}/file #
Session or Token read

The finished video.

Scope: read (since v0.131).

Parameters

id path required

The export.

string

Responses

200

The video. Cache-Control is private.

video/mp4

string · binary
404

No such export, or it has expired.

application/json

object

Every error body in the API has this shape.

code integer · int32 required

Mirrors the HTTP status.

error string required

Human-readable. Not a stable identifier — do not branch on it.

409

The export is not finished yet.

application/json

object

Every error body in the API has this shape.

code integer · int32 required

Mirrors the HTTP status.

error string required

Human-readable. Not a stable identifier — do not branch on it.

GET /api/v1/insights/classical #
Token reador Session

The Classical tab.

Scope: read (since v0.132). Pieces roll movements up to the whole work (Ciaccona → Partita No. 2); an opera is one piece and rank=movements with its piece opens it. A composer is the piece's composer, whoever the listen was credited to. Performers come from MusicBrainz's recording credits, or are inferred (inferred: 1) for listens that carry names only; a concerto counts in full for its soloist, conductor and orchestra, so performer shares do not sum to 100%.

Parameters

rank query

pieces (default), movements (needs piece), composers, performances, conductor, orchestra, ensemble or soloist.

string
range query

today, d7, month, year or all (default), as on Top Charts.

string
metric query

hours (default), plays or hearings — complete hearings, every movement of a piece in one sitting; pieces and composers only.

string
composer query

Narrow to one composer: a key from a composers row.

string
piece query

Narrow to one piece: a key from a pieces row.

string
performer query

Narrow to one performer: a key from a performer row.

string
instrument query

With rank=soloist: one instrument or voice, e.g. violin.

string
limit query
integer · int64

Responses

200

OK.

application/json

object
rank string required
metric string required
rows array required
each item
object

One row of a Classical, Scores or lens ranking.

key string required

What a filter or an expanded row passes back: a piece key, a composer's MBID, a performer's folded name.

name string required
sub string | null

The secondary line: a piece's composer, a performer's instrument.

album string | null
album_artist string | null
plays integer · int64 required
seconds integer · int64 required
versions integer | null · int64

Pieces: how many recordings you heard it in. Composers and performers: how many pieces. Songs in a lens: how many artists' versions.

hearings integer | null · int64

Complete hearings: every movement in one sitting. Pieces and composers.

inferred integer | null · int64

1 where this performer's role was inferred rather than stated.

artwork_url string | null
caa_id integer | null · int64
caa_release_mbid string | null
instruments array required

Instruments and voices the soloists in this window played, most heard first — the chips under "Soloists".

each item
object
name string required
count integer · int64 required
coverage object | null

For a performer ranking: how much of the window rests on roles MusicBrainz states, and how much on roles Tapedeck inferred.

seconds integer · int64 required
stated integer · int64 required

Seconds whose performers MusicBrainz states.

inferred integer · int64 required

Seconds with roles only Tapedeck inferred.

pending integer · int64 required

Listens the classifier has not reached yet. They are in Top Charts until it does.

400

Malformed or rejected input.

application/json

object

Every error body in the API has this shape.

code integer · int32 required

Mirrors the HTTP status.

error string required

Human-readable. Not a stable identifier — do not branch on it.

401

No valid session cookie or token. Also returned when a token is presented to a session-only endpoint — the endpoint does not accept tokens at all, so the scope is irrelevant.

application/json

object

Every error body in the API has this shape.

code integer · int32 required

Mirrors the HTTP status.

error string required

Human-readable. Not a stable identifier — do not branch on it.

{
  "code": 401,
  "error": "Authentication required. Log in to access this endpoint."
}
GET /api/v1/insights/scores #
Token reador Session

The Scores & Ambient tab.

Scope: read (since v0.132). Score is instrumental music on a soundtrack — a song on a soundtrack stays a song, and in Top Charts. Ambient is an album whose top genre on MusicBrainz is ambient.

Parameters

section query

all (default), score or ambient.

string
kind query

tracks (default), albums or artists.

string
range query
string
metric query

plays (default) or hours.

string
limit query
integer · int64

Responses

200

OK.

application/json

object
section string required
kind string required
rows array required
each item
object

One row of a chart. sub is the secondary line — an album's or track's artist — and is null for an artist chart, where the name says it all.

name string required
sub string | null
album string | null

Only set on a tracks chart — the record the track is on, so the row can open the album like every other track listing in the app.

artist_credit string | null

Only set on a tracks chart: everyone credited, "; "-joined and primary first, when there is more than one. sub is the primary alone.

album_artist string | null

Only set on a tracks chart: who album is filed under, which opens it.

plays integer · int64 required
seconds integer · int64 required
artwork_url string | null

A cover, from one of the listens counted.

caa_id integer | null · int64
caa_release_mbid string | null
suggestions array required

Albums that look like score — a soundtrack credited to its composer alone — but are not moved without your word. Confirm one with an album override setting score; dismiss it by clearing score_suggested.

each item
object

One row of a Classical, Scores or lens ranking.

key string required

What a filter or an expanded row passes back: a piece key, a composer's MBID, a performer's folded name.

name string required
sub string | null

The secondary line: a piece's composer, a performer's instrument.

album string | null
album_artist string | null
plays integer · int64 required
seconds integer · int64 required
versions integer | null · int64

Pieces: how many recordings you heard it in. Composers and performers: how many pieces. Songs in a lens: how many artists' versions.

hearings integer | null · int64

Complete hearings: every movement in one sitting. Pieces and composers.

inferred integer | null · int64

1 where this performer's role was inferred rather than stated.

artwork_url string | null
caa_id integer | null · int64
caa_release_mbid string | null
pending integer · int64 required
400

Malformed or rejected input.

application/json

object

Every error body in the API has this shape.

code integer · int32 required

Mirrors the HTTP status.

error string required

Human-readable. Not a stable identifier — do not branch on it.

401

No valid session cookie or token. Also returned when a token is presented to a session-only endpoint — the endpoint does not accept tokens at all, so the scope is irrelevant.

application/json

object

Every error body in the API has this shape.

code integer · int32 required

Mirrors the HTTP status.

error string required

Human-readable. Not a stable identifier — do not branch on it.

{
  "code": 401,
  "error": "Authentication required. Log in to access this endpoint."
}
GET /api/v1/insights/lenses #
Token reador Session

The seasonal lenses, and which are in season today.

Scope: read (since v0.132). Christmas runs 1 September – 6 January, Halloween 1 October – 2 November, Easter Palm Sunday – Easter Monday (Western date), all by your own calendar. A lens takes nothing out of Top Charts; it adds a view.

Responses

200

OK.

application/json

object
lenses array required
each item
object
id string required

christmas, halloween or easter.

label string required
in_season boolean required

Whether today, in your timezone, is in its season — when a tab shows.

season integer · int32 required

The season running, or the last one: the year it began.

starts string required
ends string required
listens integer · int64 required

All-time listens carrying it.

classical integer · int64 required

All-time listens in the two split tabs, for their cards on B-Sides.

score integer · int64 required
ambient integer · int64 required
pending integer · int64 required
401

No valid session cookie or token. Also returned when a token is presented to a session-only endpoint — the endpoint does not accept tokens at all, so the scope is irrelevant.

application/json

object

Every error body in the API has this shape.

code integer · int32 required

Mirrors the HTTP status.

error string required

Human-readable. Not a stable identifier — do not branch on it.

{
  "code": 401,
  "error": "Authentication required. Log in to access this endpoint."
}
GET /api/v1/insights/lenses/{id} #
Token reador Session

One seasonal lens: its charts, its curve, and when your season opened.

Scope: read (since v0.132). range=season (the default) charts the chosen season; year and all chart wider windows by the same flag.

Parameters

id path required

christmas, halloween or easter.

string
season query

The season, by the year it began. The running or most recent one when absent.

integer · int32
range query

season (default), year or all.

string
rank query

songs (default; covers of one song are one row), artists or albums.

string
metric query

plays (default) or hours.

string
limit query
integer · int64

Responses

200

OK.

application/json

object
id string required
label string required
season integer · int32 required
starts string required
ends string required
in_season boolean required
seasons array required

Every season you have listens in, newest first.

each item
integer · int32
range string required
rank string required
rows array required
each item
object

One row of a Classical, Scores or lens ranking.

key string required

What a filter or an expanded row passes back: a piece key, a composer's MBID, a performer's folded name.

name string required
sub string | null

The secondary line: a piece's composer, a performer's instrument.

album string | null
album_artist string | null
plays integer · int64 required
seconds integer · int64 required
versions integer | null · int64

Pieces: how many recordings you heard it in. Composers and performers: how many pieces. Songs in a lens: how many artists' versions.

hearings integer | null · int64

Complete hearings: every movement in one sitting. Pieces and composers.

inferred integer | null · int64

1 where this performer's role was inferred rather than stated.

artwork_url string | null
caa_id integer | null · int64
caa_release_mbid string | null
plays integer · int64 required

The season's own listens and seconds, and their share of everything you played in it — the same population, both skip-free.

seconds integer · int64 required
share_pct integer | null · int64
opened string | null

The day your season opened: the first of three days running when it was at least three times its level in the months before.

curve array required

One point per day from just before the season to its end (or today).

each item
object
date string required
plays integer · int64 required

Everything played that day.

season_plays integer · int64 required

The season's music among it.

share number · double required
out_of_season integer · int64 required

Listens carrying it that fell outside every season — "Christmas in July".

pending integer · int64 required
400

Malformed or rejected input.

application/json

object

Every error body in the API has this shape.

code integer · int32 required

Mirrors the HTTP status.

error string required

Human-readable. Not a stable identifier — do not branch on it.

401

No valid session cookie or token. Also returned when a token is presented to a session-only endpoint — the endpoint does not accept tokens at all, so the scope is irrelevant.

application/json

object

Every error body in the API has this shape.

code integer · int32 required

Mirrors the HTTP status.

error string required

Human-readable. Not a stable identifier — do not branch on it.

{
  "code": 401,
  "error": "Authentication required. Log in to access this endpoint."
}
404

No such resource, or it belongs to another user.

application/json

object

Every error body in the API has this shape.

code integer · int32 required

Mirrors the HTTP status.

error string required

Human-readable. Not a stable identifier — do not branch on it.

GET /api/v1/insights/versions #
Token reador Session

Every artist's version of one song you heard — the covers behind a row.

Scope: read (since v0.132).

Parameters

piece query required

A key from a songs row.

string

Responses

200

OK.

application/json

object
rows array required
each item
object

One row of a Classical, Scores or lens ranking.

key string required

What a filter or an expanded row passes back: a piece key, a composer's MBID, a performer's folded name.

name string required
sub string | null

The secondary line: a piece's composer, a performer's instrument.

album string | null
album_artist string | null
plays integer · int64 required
seconds integer · int64 required
versions integer | null · int64

Pieces: how many recordings you heard it in. Composers and performers: how many pieces. Songs in a lens: how many artists' versions.

hearings integer | null · int64

Complete hearings: every movement in one sitting. Pieces and composers.

inferred integer | null · int64

1 where this performer's role was inferred rather than stated.

artwork_url string | null
caa_id integer | null · int64
caa_release_mbid string | null
401

No valid session cookie or token. Also returned when a token is presented to a session-only endpoint — the endpoint does not accept tokens at all, so the scope is irrelevant.

application/json

object

Every error body in the API has this shape.

code integer · int32 required

Mirrors the HTTP status.

error string required

Human-readable. Not a stable identifier — do not branch on it.

{
  "code": 401,
  "error": "Authentication required. Log in to access this endpoint."
}
GET /api/v1/insights/lenses/{id}/image #
Token reador Session

A season as a share card (PNG).

Scope: read (since v0.132). The season's plays and share, the day it opened, its daily curve, the artist you played most and what was on repeat.

Parameters

id path required

christmas, halloween or easter.

string
season query
integer · int32
size query

story (default), square or wide. The image only.

string
theme query

dark (default) or light.

string

Responses

200

A PNG.

image/png

400

Malformed or rejected input.

application/json

object

Every error body in the API has this shape.

code integer · int32 required

Mirrors the HTTP status.

error string required

Human-readable. Not a stable identifier — do not branch on it.

401

No valid session cookie or token. Also returned when a token is presented to a session-only endpoint — the endpoint does not accept tokens at all, so the scope is irrelevant.

application/json

object

Every error body in the API has this shape.

code integer · int32 required

Mirrors the HTTP status.

error string required

Human-readable. Not a stable identifier — do not branch on it.

{
  "code": 401,
  "error": "Authentication required. Log in to access this endpoint."
}
404

No such resource, or it belongs to another user.

application/json

object

Every error body in the API has this shape.

code integer · int32 required

Mirrors the HTTP status.

error string required

Human-readable. Not a stable identifier — do not branch on it.

GET /api/v1/insights/lenses/{id}/mixdown #
Token reador Session

A season as a Mixdown — the year's scenes, told for the season.

Scope: read (since v0.132). Played exactly as GET /api/v1/reports/mixdown describes.

Parameters

id path required

christmas, halloween or easter.

string
season query
integer · int32
size query

story (default), square or wide. The image only.

string
theme query

dark (default) or light.

string

Responses

200

The mixdown.

application/json

object

A mixdown, and whether this server can turn it into a video.

width integer · int32 required
height integer · int32 required
fps integer · int32 required

The video's frame rate. A player may draw more often than this.

unit string required
label string required

The period's own name: "2026", "August 2026", "Week of 17 August".

theme string required
background string required

SVG drawn under every scene and never animated.

scenes array required
each item
object

A few seconds about one fact.

id string required

What the scene is about: intro, volume, shape, artist, record, discovery or outro. A period with nothing to say about one of these has no such scene.

duration_ms integer · int32 required
fade_out_ms integer · int32 required

How long the scene takes to fade into the next one, at its end. Zero for the last scene, which is held.

layers array required

Bottom first.

each item
object

One thing on screen: a piece of SVG and how it moves.

svg string required

SVG elements in mixdown coordinates (no <svg> root). Text is already fitted and escaped; draw it as it is.

origin array required

The point scales are taken about, in mixdown pixels.

each item
number · float
tracks object required

How one layer moves. Every track is optional; an empty one means the property stays at rest (opacity 1, no offset, scale 1).

Before a track's first key the value is the first key's, after its last the last key's, and between two keys it eases out (cubic) from one to the other.

opacity array
each item
object

One point on a track: at t milliseconds into the scene the value is v.

t integer · int32 required

Deeper structure omitted. The spec is the full reference.

v number · float required

Deeper structure omitted. The spec is the full reference.

dx array

Horizontal offset in mixdown pixels.

each item
object

One point on a track: at t milliseconds into the scene the value is v.

t integer · int32 required

Deeper structure omitted. The spec is the full reference.

v number · float required

Deeper structure omitted. The spec is the full reference.

dy array

Vertical offset in mixdown pixels; positive is down.

each item
object

One point on a track: at t milliseconds into the scene the value is v.

t integer · int32 required

Deeper structure omitted. The spec is the full reference.

v number · float required

Deeper structure omitted. The spec is the full reference.

scale array

Uniform scale about the layer's origin.

each item
object

One point on a track: at t milliseconds into the scene the value is v.

t integer · int32 required

Deeper structure omitted. The spec is the full reference.

v number · float required

Deeper structure omitted. The spec is the full reference.

scale_x array

Horizontal scale about the origin, multiplied with scale.

each item
object

One point on a track: at t milliseconds into the scene the value is v.

t integer · int32 required

Deeper structure omitted. The spec is the full reference.

v number · float required

Deeper structure omitted. The spec is the full reference.

scale_y array

Vertical scale about the origin, multiplied with scale.

each item
object

One point on a track: at t milliseconds into the scene the value is v.

t integer · int32 required

Deeper structure omitted. The spec is the full reference.

v number · float required

Deeper structure omitted. The spec is the full reference.

count object | null

Present when svg carries the {{n}} token.

from integer · int64 required
to integer · int64 required
start_ms integer · int32 required
end_ms integer · int32 required
fully_covered boolean required

False when a string that is drawn contains a character the embedded fonts cannot draw. The video may then show boxes for it; a browser, which has its own fonts, usually will not.

video_export boolean required

True when the server has an encoder and POST /api/v1/reports/mixdown/video will work. False is not an error: the mixdown still plays, there is just nothing to download.

401

No valid session cookie or token. Also returned when a token is presented to a session-only endpoint — the endpoint does not accept tokens at all, so the scope is irrelevant.

application/json

object

Every error body in the API has this shape.

code integer · int32 required

Mirrors the HTTP status.

error string required

Human-readable. Not a stable identifier — do not branch on it.

{
  "code": 401,
  "error": "Authentication required. Log in to access this endpoint."
}
404

No such resource, or it belongs to another user.

application/json

object

Every error body in the API has this shape.

code integer · int32 required

Mirrors the HTTP status.

error string required

Human-readable. Not a stable identifier — do not branch on it.

POST /api/v1/insights/lenses/{id}/mixdown/video #
Token reador Session

Make a video of a season's Mixdown.

Scope: read (since v0.132). The same job as POST /api/v1/reports/mixdown/video; poll and download it there.

Parameters

id path required

christmas, halloween or easter.

string
season query
integer · int32
size query

story (default), square or wide. The image only.

string
theme query

dark (default) or light.

string

Responses

202

Started.

application/json

object

Where a video export has got to.

id string required
state string required

queued (another render is running), rendering, done or failed.

frames_done integer · int32 required
frames_total integer · int32 required
bytes integer · int64 required

The file's size once state is done, otherwise 0.

error string | null

Why it failed, when it did.

401

No valid session cookie or token. Also returned when a token is presented to a session-only endpoint — the endpoint does not accept tokens at all, so the scope is irrelevant.

application/json

object

Every error body in the API has this shape.

code integer · int32 required

Mirrors the HTTP status.

error string required

Human-readable. Not a stable identifier — do not branch on it.

{
  "code": 401,
  "error": "Authentication required. Log in to access this endpoint."
}
404

No such resource, or it belongs to another user.

application/json

object

Every error body in the API has this shape.

code integer · int32 required

Mirrors the HTTP status.

error string required

Human-readable. Not a stable identifier — do not branch on it.

409

You already have a video being made.

application/json

object

Every error body in the API has this shape.

code integer · int32 required

Mirrors the HTTP status.

error string required

Human-readable. Not a stable identifier — do not branch on it.

501

This server has no video encoder.

application/json

object

Every error body in the API has this shape.

code integer · int32 required

Mirrors the HTTP status.

error string required

Human-readable. Not a stable identifier — do not branch on it.

POST /api/v1/insights/lenses/{id}/playlist #
Token writeor Session

Save a season's most-played songs as a playlist.

Scope: write (since v0.132). Your own history only — up to fifty songs you played that season, most played first. Saving the same season again returns the playlist already made. Push it to a media server from Playlists like any other.

Parameters

id path required

christmas, halloween or easter.

string
season query
integer · int32
size query

story (default), square or wide. The image only.

string
theme query

dark (default) or light.

string

Responses

200

Saved.

application/json

object
id integer · int64 required
created boolean required

False when this season's playlist already existed and was returned.

tracks integer required
401

No valid session cookie or token. Also returned when a token is presented to a session-only endpoint — the endpoint does not accept tokens at all, so the scope is irrelevant.

application/json

object

Every error body in the API has this shape.

code integer · int32 required

Mirrors the HTTP status.

error string required

Human-readable. Not a stable identifier — do not branch on it.

{
  "code": 401,
  "error": "Authentication required. Log in to access this endpoint."
}
404

No such resource, or it belongs to another user.

application/json

object

Every error body in the API has this shape.

code integer · int32 required

Mirrors the HTTP status.

error string required

Human-readable. Not a stable identifier — do not branch on it.

GET /api/v1/insights/composition #
Token reador Session

What your listening is made of, month by month.

Scope: read (since v0.132). Seconds of classical, score & ambient and everything else — each listen counted once, classical first — with the seasonal lenses as overlays inside them. Statistics keeps every listen in its own figures; this is the one chart that says what share was which.

Parameters

range query

year (default) or all.

string

Responses

200

OK.

application/json

object
months array required
each item
object
month string required

YYYY-MM, in your timezone.

seconds integer · int64 required

Every second played. The three bands below add up to it.

classical integer · int64 required
score integer · int64 required

Score and ambient, minus anything already counted as classical.

other integer · int64 required
christmas integer · int64 required

Overlays: also inside the bands above.

halloween integer · int64 required
easter integer · int64 required
capped boolean required

True when the window holds more listens than this instance reads for analytics, and the oldest months are missing.

pending integer · int64 required
401

No valid session cookie or token. Also returned when a token is presented to a session-only endpoint — the endpoint does not accept tokens at all, so the scope is irrelevant.

application/json

object

Every error body in the API has this shape.

code integer · int32 required

Mirrors the HTTP status.

error string required

Human-readable. Not a stable identifier — do not branch on it.

{
  "code": 401,
  "error": "Authentication required. Log in to access this endpoint."
}
GET /api/v1/insights/classical/stats #
Token reador Session

Statistics of your classical listening.

Scope: read (since v0.132). After Bachtrack's annual classical music statistics, refitted from concerts to listens: by period and form, your top composers year by year with their anniversaries, how much is by living composers and by women, where composers and performers are from, and the performers who took you across the most composers. Composer facts come from MusicBrainz; known says how much of the window they cover.

Parameters

range query

today, d7, month, year or all (default).

string

Responses

200

OK.

application/json

object
seconds integer · int64 required
periods array required

Seconds by Bachtrack's seven periods, by composition year, else the composer's mid-career. dated is how many of those seconds were placed by a composition year.

each item
object
name string required
seconds integer · int64 required
plays integer · int64 required
count integer | null · int64

Composers or performers behind it, where that is counted.

dated integer · int64 required
unplaced integer · int64 required
forms array required
each item
object
name string required
seconds integer · int64 required
plays integer · int64 required
count integer | null · int64

Composers or performers behind it, where that is counted.

years object required
years array required
each item
integer · int32
composers array required
each item
object
key string required
name string required
plays array required

Plays per year, aligned with ClassicalYears::years.

each item
integer · int64
anniversaries array required

Round anniversaries inside those years.

each item
object
year integer · int32 required
label string required
living object required
seconds integer · int64 required

Seconds in the subset, of known seconds whose composer is described.

known integer · int64 required
composers array required
each item
object
name string required
seconds integer · int64 required
plays integer · int64 required
count integer | null · int64

Composers or performers behind it, where that is counted.

women object required

Women and non-binary composers.

seconds integer · int64 required

Seconds in the subset, of known seconds whose composer is described.

known integer · int64 required
composers array required
each item
object
name string required
seconds integer · int64 required
plays integer · int64 required
count integer | null · int64

Composers or performers behind it, where that is counted.

composer_countries array required
each item
object
name string required
seconds integer · int64 required
plays integer · int64 required
count integer | null · int64

Composers or performers behind it, where that is counted.

performer_countries array required
each item
object
name string required
seconds integer · int64 required
plays integer · int64 required
count integer | null · int64

Composers or performers behind it, where that is counted.

range array required
each item
object
key string required
name string required
role string required
composers integer · int64 required

Distinct composers you heard them play — Bachtrack's "countries visited", for listens.

pieces integer · int64 required
plays integer · int64 required
401

No valid session cookie or token. Also returned when a token is presented to a session-only endpoint — the endpoint does not accept tokens at all, so the scope is irrelevant.

application/json

object

Every error body in the API has this shape.

code integer · int32 required

Mirrors the HTTP status.

error string required

Human-readable. Not a stable identifier — do not branch on it.

{
  "code": 401,
  "error": "Authentication required. Log in to access this endpoint."
}
GET /api/v1/insights/classical/timeline #
Token reador Session

Your classical listening on a timeline — Chronologue's grid, drawn from your history.

Scope: read (since v0.132). One column per composer, in order of birth, and each piece you heard at the year it was composed. A piece MusicBrainz gives no year stands at its composer's mid-career, with dated: false.

Parameters

range query

today, d7, month, year or all (default).

string

Responses

200

OK.

application/json

object
composers array required

Columns, by birth.

each item
object
key string required
name string required
born integer | null · int32
died integer | null · int32
pieces array required
each item
object
key string required
title string required
composer string required
year integer · int32 required

Where it stands: the year composed, or the composer's mid-career.

dated boolean required

True when year is the composition year MusicBrainz records.

plays integer · int64 required
seconds integer · int64 required
unplaced integer · int64 required

Pieces with neither a composition year nor a composer's birth year.

401

No valid session cookie or token. Also returned when a token is presented to a session-only endpoint — the endpoint does not accept tokens at all, so the scope is irrelevant.

application/json

object

Every error body in the API has this shape.

code integer · int32 required

Mirrors the HTTP status.

error string required

Human-readable. Not a stable identifier — do not branch on it.

{
  "code": 401,
  "error": "Authentication required. Log in to access this endpoint."
}
GET /api/v1/insights/anniversaries #
Token reador Session

Anniversaries among what you listen to.

Scope: read (since v0.132). Births and deaths of artists and composers, bands forming and splitting, and albums' releases — round numbers only (10, 20, 25, 30 … 100, 75, every 50), from MusicBrainz's dates. Only artists and albums in your own history.

Parameters

year query

The year to mark; this year, in your timezone, when absent.

integer · int32

Responses

200

OK.

application/json

object
year integer · int32 required
items array required

Round anniversaries this year of artists, composers and albums in your history, most played first.

each item
object
kind string required

born, died, formed, split or released.

name string required

The artist, or the album.

artist string | null

For an album: who it is filed under.

date string required

YYYY[-MM[-DD]], as MusicBrainz has it.

years integer · int32 required
living boolean required

For a person: alive, as far as MusicBrainz knows.

today boolean required

Falls on today's date (month and day), not only in this year.

plays integer · int64 required

Your plays of them, all time.

label string required

The sentence to show.

today array required

Birthdays and deathdays falling on today's date.

each item
object
kind string required

born, died, formed, split or released.

name string required

The artist, or the album.

artist string | null

For an album: who it is filed under.

date string required

YYYY[-MM[-DD]], as MusicBrainz has it.

years integer · int32 required
living boolean required

For a person: alive, as far as MusicBrainz knows.

today boolean required

Falls on today's date (month and day), not only in this year.

plays integer · int64 required

Your plays of them, all time.

label string required

The sentence to show.

revisit array required

Albums with a round anniversary this year that you have not played for half a year — for Rediscovery.

each item
object
kind string required

born, died, formed, split or released.

name string required

The artist, or the album.

artist string | null

For an album: who it is filed under.

date string required

YYYY[-MM[-DD]], as MusicBrainz has it.

years integer · int32 required
living boolean required

For a person: alive, as far as MusicBrainz knows.

today boolean required

Falls on today's date (month and day), not only in this year.

plays integer · int64 required

Your plays of them, all time.

label string required

The sentence to show.

401

No valid session cookie or token. Also returned when a token is presented to a session-only endpoint — the endpoint does not accept tokens at all, so the scope is irrelevant.

application/json

object

Every error body in the API has this shape.

code integer · int32 required

Mirrors the HTTP status.

error string required

Human-readable. Not a stable identifier — do not branch on it.

{
  "code": 401,
  "error": "Authentication required. Log in to access this endpoint."
}
GET /api/v1/insights/overrides #
Token reador Session

Your corrections on one piece, album or artist.

Scope: read (since v0.132).

Parameters

target_kind query required

work, album or artist.

string
target_key query required
string

Responses

200

OK.

application/json

object
overrides array required

Your corrections on that target. Empty means Tapedeck decides.

each item
object
facet string required
value boolean required
401

No valid session cookie or token. Also returned when a token is presented to a session-only endpoint — the endpoint does not accept tokens at all, so the scope is irrelevant.

application/json

object

Every error body in the API has this shape.

code integer · int32 required

Mirrors the HTTP status.

error string required

Human-readable. Not a stable identifier — do not branch on it.

{
  "code": 401,
  "error": "Authentication required. Log in to access this endpoint."
}
POST /api/v1/insights/overrides #
Token writeor Session

Correct what kind of listen something is.

Scope: write (since v0.132). Yours only: overrides never change what another member of this instance sees. Applied at once, from what Tapedeck already knows — nothing is looked up.

Request body required

application/json

object
target_kind string required

work — a piece or song, every version of it (key: a row's key from a lens or Classical, which starts w: or t:); album (key: a Scores suggestion's key); or artist (key: the artist's name) — everything they are credited on. Broadest first, most specific wins: artist, then album, then piece.

target_key string required
facet string required

classical, score, ambient, christmas, halloween, easter or score_suggested.

value boolean | null

true sets it, false clears it, null removes your override and returns to what Tapedeck decided. Required: an absent value is a 400, so a client that forgot it cannot quietly undo a correction.

Responses

200

Applied.

application/json

object
listens integer · int64 required

Listens the change touched, already re-applied.

400

Malformed or rejected input.

application/json

object

Every error body in the API has this shape.

code integer · int32 required

Mirrors the HTTP status.

error string required

Human-readable. Not a stable identifier — do not branch on it.

401

No valid session cookie or token. Also returned when a token is presented to a session-only endpoint — the endpoint does not accept tokens at all, so the scope is irrelevant.

application/json

object

Every error body in the API has this shape.

code integer · int32 required

Mirrors the HTTP status.

error string required

Human-readable. Not a stable identifier — do not branch on it.

{
  "code": 401,
  "error": "Authentication required. Log in to access this endpoint."
}
GET /api/v1/charts #
Token reador Session

Top charts.

Scope: read (since v0.120). Note this offers a different range set from /api/v1/stats — it has today. The two answering the same question over different windows is known, and is why the Insights redesign wants one shared range control.

Parameters

kind query

artists (default), albums or tracks.

string
range query

The window, as on GET /api/v1/stats: today, d7, month, year or all, the default.

string
limit query

100 by default, at most 500.

integer · int64
metric query

plays (default) or hours — the ranking, not just the number shown. Statistics hands off here carrying its own metric, and the two lists disagreeing would defeat the point of the handoff.

string

Responses

200

OK.

application/json

object

Ranked chart over one window. The Statistics page shows the head of these three lists; this serves the whole thing for the dedicated charts screen. A ranked chart.

kind string required

artists, albums or tracks.

range string required

The window, as asked.

rows array required
each item
object

One row of a chart. sub is the secondary line — an album's or track's artist — and is null for an artist chart, where the name says it all.

name string required
sub string | null
album string | null

Only set on a tracks chart — the record the track is on, so the row can open the album like every other track listing in the app.

artist_credit string | null

Only set on a tracks chart: everyone credited, "; "-joined and primary first, when there is more than one. sub is the primary alone.

album_artist string | null

Only set on a tracks chart: who album is filed under, which opens it.

plays integer · int64 required
seconds integer · int64 required
artwork_url string | null

A cover, from one of the listens counted.

caa_id integer | null · int64
caa_release_mbid string | null
split_out integer · int64 required

Listens in the window left out because they are classical or score and you keep those in their own tabs (preferences split_classical, split_scores). Zero when you do not.

400

Malformed or rejected input.

application/json

object

Every error body in the API has this shape.

code integer · int32 required

Mirrors the HTTP status.

error string required

Human-readable. Not a stable identifier — do not branch on it.

401

No valid session cookie or token. Also returned when a token is presented to a session-only endpoint — the endpoint does not accept tokens at all, so the scope is irrelevant.

application/json

object

Every error body in the API has this shape.

code integer · int32 required

Mirrors the HTTP status.

error string required

Human-readable. Not a stable identifier — do not branch on it.

{
  "code": 401,
  "error": "Authentication required. Log in to access this endpoint."
}