How to Access Play History

Users might want to have access to the songs they sang recently to easily be able to sing them again. Karaoke-api offers the feature to retrieve the listening history of a user up to at most 200 recent songs.

Requirements

You must have a valid API key and Bearer Token. For information on how to get the token, refer to Generating Access Tokens.

To run the tutorial, you must download the full OpenAPI specification and then import it into an API testing platform. For this tutorial, we will be using Postman API. For information on how to use Postman, refer to their documentation.

Retrieving listening history

The listening history of a user is built automatically when calling the \v2\play-log endpoint, and only the 200 most recent distinct songs are kept in the user history. To retrieve the history, we must call POST \v2\profile\history with the following query parameter options:

• size: (Optional) Set the number of entries to return in the results. By default, 10 songs are returned.
• page: (Optional) Enter the specific results page number to return. By default, the first page is returned (page=0).

Result

The endpoint returns a list of songs in the reverse order they were listened to (most recent first).

Figure 1: Step 1 sample response

[
  {
    "thumbnails": {
      "album": "{thumbnail filePath}"
    },
    "id": "KAR:G:2411566",
    "title": "What's It Gonna Be",
    "duration_sec": 321,
    "genre": {
      "id": "3",
      "label": "R&B/Hip-Hop"
    },
    // other paramaters
    "added_date": "2022-04-25"
    // other parameters
  },
  {
    "thumbnails": {
      "album": "{thumbnail filePath}"
    },
    "id": "KAR:G:3259333",
    "title": "We Don't Talk About Bruno (Duet)",
    "duration_sec": 213,
    "genre": {
      "id": "12",
      "label": "Disney"
    },
    // other parameters
    "added_date": "2022-04-08"
    // other parameters
  },
  {
    "thumbnails": {
      "album": "{thumbnail filePath}"
    },
    "id": "KAR:G:3583",
    "title": "From This Moment On (Duet)",
    "duration_sec": 225,
    "genre": {
      "id": "6",
      "label": "Country"
    },
    // other parameters
    "added_date": "2022-03-03"
    // other parameters
  },
  {
    "thumbnails": {
      "album": "{thumbnail filePath}"
    },
    "id": "KAR:G:7556",
    "title": "That's Another Story (Duet)",
    "duration_sec": 210,
    "genre": {
      "id": "6",
      "label": "Country"
    },
    // other parameters
    "added_date": "2021-12-01"
    // other parameters
  },
  {
    "thumbnails": {
      "album": "{thumbnail filePath}"
    },
    "id": "KAR:G:2542509",
    "title": "Have Yourself A Merry Little Christmas",
    "duration_sec": 217,
    "genre": {
      "id": "1",
      "label": "Holiday"
    },
    // other parameters
    "added_date": "2021-08-20"
    // other parameters
  }
]

Clearing listening history

To clear the listening history of a user, we must call DELETE \v2\profile\history. This will remove every song in their history.

Result

A status code of 204 mean the history was cleared successfully.