Listening

Top albums

GET https://api.rewind.rest/v1/listening/top/albums

Returns top albums for a given time period. Pass include_sparklines=true to attach a play-count time series per album (1month/3month/6month/12month/overall).

Authorization

Authorizationheaderstringrequired

API key. Read keys (rw_live_...) access GET endpoints. Admin keys (rw_admin_...) access all endpoints.

Query Parameters

periodqueryenum (string)

Allowed values7day1month3month6month12monthoverall

pagequeryinteger

limitqueryinteger

datequerystring

Single day (YYYY-MM-DD). Overrides from/to.

fromquerystring

Range start, inclusive (ISO 8601)

toquerystring

Range end, inclusive (ISO 8601)

include_sparklinesqueryboolean

When true, attach a sparkline object (granularity + zero-filled points) to each item. On rolling-period endpoints, supported for period in {1month, 3month, 6month, 12month, overall}. overall returns yearly buckets covering the artist/album/track lifetime; 7day is unsupported and the field is omitted.

Response

application/json

Top albums list

periodstringrequired

dataarray of objectrequired

properties

paginationobjectrequired

properties

cURL

curl -X GET 'https://api.rewind.rest/v1/listening/top/albums' \
  -H 'Authorization: Bearer <token>'

200

{
  "period": "string",
  "data": [
    {
      "rank": 0,
      "id": 0,
      "name": "string",
      "detail": "string",
      "playcount": 0,
      "image": {},
      "url": "string",
      "apple_music_url": "string",
      "preview_url": "string",
      "sparkline": {
        "granularity": "\u2026",
        "points": "\u2026"
      }
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 150,
    "total_pages": 8
  }
}