Skip to main content
POST
/
ws
/
1.1
/
track.lyrics.analysis.search
curl --request POST \ --url 'https://api.musixmatch.com/ws/1.1/track.lyrics.analysis.search?apikey=' \ --header 'Content-Type: application/json' \ --data ' { "data": { "meaning": "self empowerment and overcoming obstacles" } } '
{ "message": { "header": { "status_code": 200, "execute_time": 0.12, "available": 1500 }, "body": { "track_list": [ { "track": { "track_id": 12345678, "track_name": "Bohemian Rhapsody", "artist_name": "Queen", "album_name": "A Night at the Opera", "commontrack_id": 7654321, "first_release_date": "1975-10-31T00:00:00Z", "track_share_url": "https://www.musixmatch.com/lyrics/Queen/Bohemian-Rhapsody" }, "analysis": { "meaning": { "explanation": "A song about a young man confessing to murder and facing the consequences of his actions.", "description": "Generates a simple, short explanation of the lyrics' content." }, "themes": { "main_themes": [ { "theme": "guilt and redemption", "quotes": [ "Mama, just killed a man", "Is this the real life? Is this just fantasy?" ] } ], "description": "Extracts a list of the main themes covered by the song's lyrics." }, "moods": { "main_moods": [ "Angst", "Despair" ], "description": "Extracts a list of moods from the lyrics." }, "rating": { "audience": "PG-13", "descriptor": "Thematic elements of violence and death", "description": "Assigns a parental guide rating to the lyrics." }, "religion": { "has_references": false, "referenced_religions": [], "description": "Identifies references to religions within the lyrics." }, "entities": { "entity_list": [ { "entity_name": "Galileo", "categories": [ "People & Groups" ], "occurrences": 4 } ], "description": "Identifies and categorizes specific elements like names, locations, dates." }, "moderation": { "needs_moderation": false, "categories": [ { "category": "violence", "score": 0.15, "is_present": false } ], "description": "Identifies content categories that may require moderation." }, "explicitness": { "has_profanities": false, "description": "Examines a text to find offensive or inappropriate words." } } } ] } } }
Search tracks by lyrics analysis criteria — moods, themes, meaning, entities, moderation, rating, and more. This endpoint enables analysis-driven discovery: find songs about specific topics, with certain moods, mentioning particular entities, or matching content safety criteria. Search parameters are passed in the request body under a data key, while pagination is controlled via query parameters. For detailed information about the analysis metadata returned in the response, please refer to the Analysis documentation.

​
Input Constraints

  • Maximum string length: 500 characters (meaning, themes[], genre[], entities[].name)
  • Maximum array size: 20 items (themes, entities, genre, moods, religions, moderation_categories)

​
Entities

The entities parameter accepts an array of objects. Each object must have at least one of name or category.
  • Fields within an object are AND-ed (e.g. name=Paris AND category=Geographical Locations)
  • Multiple objects are OR-ed (e.g. Paris OR London)

​
Available Moods

Love, Heartbreak, Joy, Empowerment, Angst, Reflection, Inspiration, Nostalgia, Despair, Celebration, Anger, Peace, Solitude, Adventure, Social Commentary, Hope, Spirituality, Freedom, Party, Nature

​
Rating Values

ValueDescription
GGeneral audiences
PGParental guidance suggested
PG-13Parents strongly cautioned (includes G and PG)
RRestricted (includes G, PG, and PG-13)
NC-17Adults only (includes all)
Rating is hierarchical — filtering by PG-13 returns tracks rated G, PG, and PG-13.

​
Entity Categories

People & Groups, Geographical Locations, Events & Periods, Cultural Works, Organizations & Institutions, Products & Brands, Concepts & Ideas, Diseases

​
Religions

The religions parameter accepts an array of strings (religion names). Use exclude_religions: true to exclude tracks with any religious references instead.

​
Moderation Categories

The moderation_categories parameter accepts an array of strings (category names). Available categories: harassment, hate, illicit, sexual, violence, harassment/threatening, hate/threatening, illicit/violent, self-harm/intent, self-harm/instructions, self-harm, sexual/minors, violence/graphic 
"moderation_categories": ["violence"]

​
Example

A request combining multiple parameters: 
{
  "data": {
    "meaning": "songs about overcoming personal struggles and finding inner strength after loss",
    "moods": ["Empowerment", "Reflection", "Hope"],
    "themes": ["resilience", "self-discovery", "moving on"],
    "rating": "PG-13",
    "genre": ["Pop", "Alternative"],
    "moderation_categories": ["violence"],
    "entities": [
      {
        "name": "freedom",
        "category": "Concepts & Ideas"
      }
    ],
    "lyrics_language": "en",
    "first_release_date": "20200101",
    "needs_moderation": false,
    "lyrics_explicit": false
  }
}

​
Notes

  • The available count in the response header reflects total search engine hits. Actual items in track_list may be fewer, as tracks without analysis data or with metadata restrictions are skipped.
  • The analysis object in the response matches the structure of track.lyrics.analysis.get.

Authorizations

​
apikey
string
query
required

Query Parameters

​
page
integer

Page number (max 100).

Required range: 1 <= x <= 100
Example:

1

​
page_size
integer

Results per page (max 100).

Required range: 1 <= x <= 100
Example:

10

Body

application/json
​
data
object

Search parameters. At least one must be provided.

Response

200 - application/json

200 OK / 400 Bad Request / 401 Unauthorized / 403 Forbidden

​
message
object