Skip to main content
POST
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

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

Example

A request combining multiple parameters:

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