> ## 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. # track.lyrics.analysis.search > Search tracks by lyrics analysis criteria — moods, themes, meaning, entities, moderation, rating, and more. Discover music based on what songs are about rather than just metadata like title or artist. 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](/api-reference/analysis/analysis-overview). ## 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 | Value | Description | | ----- | ---------------------------------------------- | | G | General audiences | | PG | Parental guidance suggested | | PG-13 | Parents strongly cautioned (includes G and PG) | | R | Restricted (includes G, PG, and PG-13) | | NC-17 | Adults 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` ```json theme={null} "moderation_categories": ["violence"] ``` ## Example A request combining multiple parameters: ```json theme={null} { "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](/api-reference/analysis/track-lyrics-analysis-get). ## OpenAPI ````yaml post /ws/1.1/track.lyrics.analysis.search openapi: 3.0.3 info: title: Lyrics API description: >- These endpoints return metadata about songs and lyrics. For full details, see the [API reference](https://docs.musixmatch.com/lyrics-api/introduction) for these endpoints. To authenticate your API requests and use the endpoints, you need to include your API key as a **query parameter** (`apikey`) in every call, like this: `GET /ws/1.1/track.get?apikey=YOUR_API_KEY`. In Postman, enter your API Key in the **Auth** tab, where it will be automatically appended to the request. **Best Practice:** Use **Postman Vault** to securely store your key; see the official [Postman documentation](https://learning.postman.com/docs/sending-requests/postman-vault/postman-vault-secrets/) for details. Always keep your API key secure and never share it publicly. If you believe your API key has been compromised, contact us immediately at `sales@musixmatch.com`. version: 1.0.0 contact: {} servers: - url: https://api.musixmatch.com security: - apiKey: [] tags: - name: Matcher description: >- Match an external piece of information (like a title and artist) to a track in the Musixmatch catalog to retrieve its track ID, lyrics, or syncs. - name: Track description: >- Search for specific songs, and retrieve detailed information about a single track, including its lyrics, snippets, translations, and rich sync data. - name: Artist description: >- Search for artists, and retrieve detailed information about a specific artist, including their discography (albums). - name: Album description: >- Retrieve detailed information about a specific music album, including the list of tracks it contains. - name: Charts description: >- Retrieve top-ranking tracks and artists, typically based on country, as well as lists of available music genres. - name: Enterprise description: >- **For more details on the Enterprise integration refer to the** [official documentation.](https://docs.musixmatch.com/enterprise-integration/introduction) paths: /ws/1.1/track.lyrics.analysis.search: post: tags: - Track summary: track.lyrics.analysis.search description: >- Search tracks by lyrics analysis criteria — moods, themes, meaning, entities, moderation, rating, and more. Discover music based on what songs are about rather than just metadata like title or artist. operationId: trackLyricsAnalysisSearch parameters: - name: page in: query schema: type: integer example: 1 minimum: 1 maximum: 100 description: Page number (max 100). - name: page_size in: query schema: type: integer example: 10 minimum: 1 maximum: 100 description: Results per page (max 100). requestBody: content: application/json: schema: type: object properties: data: type: object description: Search parameters. At least one must be provided. minProperties: 1 properties: meaning: type: string description: Free-text search on lyrics meaning. maxLength: 500 example: self empowerment and overcoming obstacles themes: type: array items: type: string maxLength: 500 maxItems: 20 description: Search by themes (max 20 items). example: - existential crisis - rebellion moods: type: array items: type: string enum: - Love - Heartbreak - Joy - Empowerment - Angst - Reflection - Inspiration - Nostalgia - Despair - Celebration - Anger - Peace - Solitude - Adventure - Social Commentary - Hope - Spirituality - Freedom - Party - Nature description: Filter by moods (max 20 items). maxItems: 20 example: - Angst - Despair rating: type: string enum: - G - PG - PG-13 - R - NC-17 description: >- Parental rating filter. Hierarchical: PG-13 includes G and PG content. example: PG-13 religions: type: array items: type: string description: Filter by religion references in lyrics (max 20 items). maxItems: 20 exclude_religions: type: boolean description: Exclude tracks with any religious references. entities: type: array items: type: object properties: name: type: string description: Entity name (fuzzy match). maxLength: 500 example: Paris category: type: string description: Entity category (exact match). enum: - People & Groups - Geographical Locations - Events & Periods - Cultural Works - Organizations & Institutions - Products & Brands - Concepts & Ideas - Diseases example: Geographical Locations minProperties: 1 maxItems: 20 description: >- Structured entity search (max 20 items). Each object must have at least one of name or category. Fields within an object are AND-ed; multiple objects are OR-ed. example: - name: Paris category: Geographical Locations genre: oneOf: - type: string maxLength: 500 example: Pop - type: array items: type: string maxLength: 500 maxItems: 20 example: - Pop - Rock description: >- Filter by music genre. Accepts a single string or an array (max 20 items). lyrics_language: type: string description: Filter by lyrics language (2-character ISO code). example: en lyrics_explicit: type: boolean description: Filter by explicit lyrics flag. has_profanities: type: boolean description: Filter by profanity presence. first_release_date: type: string description: >- Minimum release date — tracks released on or after this date (format: YYYYMMDD). example: '20200101' needs_moderation: type: boolean description: Filter by moderation flag. moderation_categories: type: array items: type: string description: Filter by specific moderation categories (max 20 items). maxItems: 20 example: - violence - sexual examples: Search by meaning: value: data: meaning: self empowerment and overcoming obstacles Filter by moods + language: value: data: moods: - Angst - Despair lyrics_language: en Themes + rating: value: data: themes: - existential crisis rating: PG-13 Entity search + mood: value: data: entities: - name: Paris category: Geographical Locations moods: - Love Combined parameters: value: 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 responses: '200': description: 200 OK / 400 Bad Request / 401 Unauthorized / 403 Forbidden content: application/json: schema: type: object properties: message: type: object properties: header: type: object properties: status_code: type: number example: 200 execute_time: type: number example: 0.12 available: type: number description: >- Total hits from the search engine. Note: actual results in track_list may be fewer due to tracks without analysis data or with metadata restrictions being skipped. example: 1500 body: type: object properties: track_list: type: array items: type: object properties: track: type: object description: >- Standard track object (same fields as track.get). properties: track_id: type: number example: 12345678 track_name: type: string example: Bohemian Rhapsody artist_name: type: string example: Queen album_name: type: string example: A Night at the Opera commontrack_id: type: number example: 7654321 first_release_date: type: string example: '1975-10-31T00:00:00Z' track_share_url: type: string example: >- https://www.musixmatch.com/lyrics/Queen/Bohemian-Rhapsody analysis: type: object description: >- Analysis object (same structure as track.lyrics.analysis.get). properties: meaning: type: object properties: explanation: type: string example: >- A song about a young man confessing to murder and facing the consequences of his actions. description: type: string example: >- Generates a simple, short explanation of the lyrics' content. themes: type: object properties: main_themes: type: array items: type: object properties: theme: type: string example: guilt and redemption quotes: type: array items: type: string example: - Mama, just killed a man - >- Is this the real life? Is this just fantasy? description: type: string example: >- Extracts a list of the main themes covered by the song's lyrics. moods: type: object properties: main_moods: type: array items: type: string example: - Angst - Despair description: type: string example: >- Extracts a list of moods from the lyrics. rating: type: object properties: audience: type: string example: PG-13 descriptor: type: string example: Thematic elements of violence and death description: type: string example: >- Assigns a parental guide rating to the lyrics. religion: type: object properties: has_references: type: boolean example: false referenced_religions: type: array items: type: string example: [] description: type: string example: >- Identifies references to religions within the lyrics. entities: type: object properties: entity_list: type: array items: type: object properties: entity_name: type: string example: Galileo categories: type: array items: type: string example: - People & Groups occurrences: type: number example: 4 description: type: string example: >- Identifies and categorizes specific elements like names, locations, dates. moderation: type: object properties: needs_moderation: type: boolean example: false categories: type: array items: type: object properties: category: type: string example: violence score: type: number example: 0.15 is_present: type: boolean example: false description: type: string example: >- Identifies content categories that may require moderation. explicitness: type: object properties: has_profanities: type: boolean example: false description: type: string example: >- Examines a text to find offensive or inappropriate words. examples: 200 OK: value: 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. 400 Bad Request: value: message: header: status_code: 400 execute_time: 0.001 body: [] 401 Unauthorized: value: message: header: status_code: 401 execute_time: 0.001 body: [] 403 Forbidden: value: message: header: status_code: 403 execute_time: 0.001 body: [] components: securitySchemes: apiKey: type: apiKey name: apikey in: query ````