Source: https://dinakar-rewind.docs.pageloop.ai/api-reference/listening/getlisteningtoptracks

# Top tracks

GET `https://api.rewind.rest/v1/listening/top/tracks`

Returns your top tracks for a given time period, optionally scoped to a single artist.

## Authorization

#### Authorization (header, string, required)

API key. Read keys (rw\_live\_...) access GET endpoints. Admin keys (rw\_admin\_...) access all endpoints.

## Query Parameters

#### period (query, enum (string)) — allowed: 7day, 1month, 3month, 6month, 12month, overall

#### page (query, integer)

#### limit (query, integer)

#### date (query, string)

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

#### from (query, string)

Range start, inclusive (ISO 8601)

#### to (query, string)

Range end, inclusive (ISO 8601)

#### include\_sparklines (query, boolean)

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.

#### artist\_id (query, integer)

Filter top tracks to a single artist's catalog. Stable id from `get_artist_details` or `get_top_artists`. Composes with `period` and date filters.

#### artist\_name (query, string)

Substring match against `lastfm_artists.name`. Resolves to the highest-playcount artist. Use only when no `artist_id` is available; passing both is a 400.

## Response

#### 200

Top tracks list

#### period (string, required)

#### artist\_id (number)

#### data (array of object, required)

#### properties

#### rank (number, required)

#### id (number, required)

#### name (string, required)

#### detail (string, required)

#### playcount (number, required)

#### image (object)

#### url (string, required)

#### apple\_music\_url (string, required)

#### preview\_url (string)

#### sparkline (object)

#### album\_id (number)

#### album\_name (string)

#### album\_apple\_music\_url (string)

#### album\_released\_year (number)

#### album\_total\_tracks (number)

#### pagination (object, required)

#### properties

#### page (integer, required)

#### limit (integer, required)

#### total (integer, required)

#### total\_pages (integer, required)

#### 400

Bad request

#### error (string, required)

#### status (integer, required)

#### 401

Unauthorized

#### error (string, required)

#### status (integer, required)

#### Request

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

```javascript JavaScript
const res = await fetch('https://api.rewind.rest/v1/listening/top/tracks', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer <token>',
  },
});
const data = await res.json();
```

```python Python
import requests

res = requests.get(
    'https://api.rewind.rest/v1/listening/top/tracks',
    headers={'Authorization': 'Bearer <token>'}
)
data = res.json()
```

#### Response

```json 200
{
  "period": "string",
  "artist_id": 0,
  "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"
      },
      "album_id": 0,
      "album_name": "string",
      "album_apple_music_url": "string",
      "album_released_year": 0,
      "album_total_tracks": 0
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 150,
    "total_pages": 8
  }
}
```

```json 400
{
  "error": "Not found",
  "status": 404
}
```

```json 401
{
  "error": "Not found",
  "status": 404
}
```