> ## Documentation Index
> Fetch the complete documentation index at: https://docs.musixmatch.com/llms.txt
> Use this file to discover all available pages before exploring further.

# API methods

## What does the Musixmatch API do?

The Musixmatch API allows you to read objects from our huge 100% licensed lyrics database.

**Note: all these methods require authentication.**

To make your life easier we are providing you with one or more examples to show you how it could work in the wild. You’ll find both the **API request** and **API response** in all the available output formats for each API call.
If you see certain fields in the responses which are not documented/not present in the examples, such data are not to be used.

Supported input parameters can be found in the input parameters section. Use `UTF-8` to encode arguments when calling API methods.

Also, every response includes a `status_code`. A list of all status codes can be consulted below in the status codes section.

<Tip>
  **Do you have an idea or suggestion for an API call that you don’t see here?**\
  Write us at [sales@musixmatch.com](mailto:sales@musixmatch.com) and we’ll do our best to respond!
</Tip>

## Input parameters

Use `UTF-8` to encode arguments. These are the supported input parameters:

### Authentication

| Name     | Description                                                                                                                                              |
| -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `apikey` | Your personal api key, you must use it in every api call. You can pass this parameter as `GET` parameter in your api call, like `track.get?apikey=xxxx.` |

### Objects

| Name             | Description                |
| ---------------- | -------------------------- |
| `track_id`       | Musixmatch track id.       |
| `artist_id`      | Musixmatch artist id.      |
| `album_id`       | Musixmatch album id.       |
| `commontrack_id` | Musixmatch commontrack id. |

### Querying

| Name       | Description                                                          |
| ---------- | -------------------------------------------------------------------- |
| `q_track`  | Search for a text string among song titles.                          |
| `q_artist` | Search for a text string among artist names.                         |
| `q_lyrics` | Search for a text string among lyrics.                               |
| `q`        | Search for a text string among song titles, artist names and lyrics. |

### Filtering

| Name                              | Description                                                  |
| --------------------------------- | ------------------------------------------------------------ |
| `f_has_lyrics`                    | Filter by objects with available lyrics.                     |
| `f_is_instrumental`               | Filter instrumental songs.                                   |
| `f_has_subtitle`                  | Filter by objects with available subtitles.                  |
| `f_music_genre_id`                | Filter by objects with a specific music category.            |
| `f_subtitle_length`               | Filter subtitles by a given duration in seconds.             |
| `f_subtitle_length_max_deviation` | Apply a deviation to a given subtitle duration (in seconds). |
| `f_lyrics_language`               | Filter the tracks by lyrics language.                        |
| `f_artist_id`                     | Filter by objects with a given Musixmatch artist\_id.        |

### Grouping

| Name            | Description                                  |
| --------------- | -------------------------------------------- |
| `g_commontrack` | Group a track result set by commontrack\_id. |

### Sorting

| Name                   | Description                                                                             |
| ---------------------- | --------------------------------------------------------------------------------------- |
| `s_track_rating`       | Sort the results by our popularity index for tracks, possible values are `ASC / DESC`.  |
| `s_track_release_date` | Sort the results by track release date, possible values are `ASC / DESC`.               |
| `s_artist_rating`      | Sort the results by our popularity index for artists, possible values are `ASC / DESC.` |

### Result set pagination

| Name        | Description                                                              |
| ----------- | ------------------------------------------------------------------------ |
| `page`      | Request specific result page (default=1).                                |
| `page_size` | Specify number of items per result page (default=10, range is 1 to 100). |

### Output format

| Name              | Description                                                                                  |
| ----------------- | -------------------------------------------------------------------------------------------- |
| `subtitle_format` | Desired output format for the subtitle body. Possible values `LRC / DFXP`. Default to `LRC`. |

### Localization

| Name      | Description                              |
| --------- | ---------------------------------------- |
| `country` | The country code of the desired country. |

## Status codes

All responses include a status code indicating whether a request was successful or not.

Successful responses have a status code `200`; failed requests may have different status code providing you an indication of the problem.

| Code    | Description                                                                                                    |
| ------- | -------------------------------------------------------------------------------------------------------------- |
| **200** | The request was successful.                                                                                    |
| **400** | The request had bad syntax or was inherently impossible to be satisfied.                                       |
| **401** | Authentication failed, probably because of invalid/missing API key.                                            |
| **402** | The usage limit has been reached, either you exceeded per day requests limits or your balance is insufficient. |
| **403** | You are not authorized to perform this operation.                                                              |
| **404** | The requested resource was not found.                                                                          |
| **405** | The requested method was not found.                                                                            |
| **500** | Ops. Something were wrong.                                                                                     |
| **503** | Our system is a bit busy at the moment and your request can’t be satisfied.                                    |