Embedding Batches API Documentation

Lyrics are cut into chunks, and the chunks are embedded in the background, in batches, after tracks are loaded. A search that goes by what lyrics are about (lyrical_theme in the operators reference) finds a track once its chunks are embedded. After a load, the lyrics are ready when pending and in_progress are both zero.

This endpoint is read only. A script that loads a catalog and then searches it can poll it to know when lyric searches are ready.

Endpoints

GET /api/v1/libraries/{library_id}/embedding_batches

Retrieve the library’s lyric chunks counted by state, and its embedding batches, newest first.

Path Parameters

Name	Type	Description	Required
library_id	integer	ID of the library	Yes

Query Parameters

Name	Type	Description
page	integer	Page number for pagination (default: 1)
per_page	integer	Records per page, up to 200 (default: 25)

Response

{
    "pagination": {
        "total_entries": 1,
        "per_page": 25,
        "current_page": 1,
        "total_pages": 1
    },
    "vectors": {
        "embedded": 4,
        "pending": 10882,
        "in_progress": 0,
        "given_up": 0
    },
    "embedding_batches": [
        {
            "id": 1,
            "status": "pending",
            "remote_status": null,
            "provider": "openai",
            "model": "text-embedding-3-large",
            "request_count": 0,
            "completed_count": 0,
            "failed_count": 0,
            "error_message": null,
            "submitted_at": null,
            "finished_at": null,
            "created_at": "2026-09-17T18:08:13.988-05:00",
            "updated_at": "2026-09-17T18:08:13.988-05:00"
        }
    ]
}

Response Fields

Field	Type	Description
pagination	object	Contains pagination information for the batches
vectors	object	The library’s lyric chunks, counted by state
embedded	integer	Chunks that are embedded and can be searched
pending	integer	Chunks waiting to go into a batch
in_progress	integer	Chunks in a batch that has not finished
given_up	integer	Chunks that failed and will not be tried again
embedding_batches	array	The batches
id	integer	ID of the batch
status	string	Where the batch has got to
remote_status	string \| null	What the provider says of it
provider, model	string	The AI provider and model embedding the chunks
request_count	integer	Chunks in the batch
completed_count, failed_count	integer	Chunks done, and chunks that failed
error_message	string \| null	Why the batch failed, if it did
submitted_at, finished_at	string \| null	When it went to the provider and when it came back
created_at, updated_at	string	Timestamps

HTTP Response Codes

Code	Description
`200 OK`	Successful request
`404 Not Found`	Invalid library ID