GET /getLyrics

GET /getLyrics

Try it in the playground

Fetch synced lyrics for a song, with syllable-level timing in TTML format.

Parameters

The API rejects a request (422) only when both song and artist are missing. Send all four anyway: the cache key includes album and duration, so a request without them often misses the cached entry and, without an API key, returns 401.

If you send more than one alias of a parameter (for example s and song), the values are joined together. Send only one alias of each.

Headers

Example request

curl "https://api.betterlyrics.org/getLyrics?s=E85&a=Don%20Toliver&al=OCTANE&d=154"

const res = await fetch("https://api.betterlyrics.org/getLyrics?s=E85&a=Don%20Toliver&al=OCTANE&d=154");
const { ttml } = await res.json();

import requests

res = requests.get("https://api.betterlyrics.org/getLyrics?s=E85&a=Don%20Toliver&al=OCTANE&d=154")
ttml = res.json()["ttml"]

package main

import (
	"fmt"
	"io"
	"net/http"
)

func main() {
	res, err := http.Get("https://api.betterlyrics.org/getLyrics?s=E85&a=Don%20Toliver&al=OCTANE&d=154")
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()

	body, err := io.ReadAll(res.Body)
	if err != nil {
		panic(err)
	}
	fmt.Println(string(body))
}

Success response

Status: 200 OK, Content-Type: application/json

{
  "ttml": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<tt xmlns=\"http://www.w3.org/ns/ttml\">\n  <body>\n    <div>\n      <p begin=\"00:00:18.234\" end=\"00:00:21.891\">\n        <span begin=\"00:00:18.234\" end=\"00:00:18.567\">The </span>\n        ...\n      </p>\n    </div>\n  </body>\n</tt>",
  "score": 0.97
}

Response fields

Response headers

/getLyrics does not send X-Provider. See Provider-specific endpoints for the endpoints that do.

Error responses

All error responses are JSON, except 422 and the 429 sent when both rate limit tiers are exhausted, which are plain text.

Missing parameters (422)

Sent when neither song nor artist is given. Content-Type: text/plain:

Song name or artist name not provided

API key required (401)

The query is not cached, the server enforces API keys, and the request has no key:

{
  "error": "API key required",
  "message": "Uncached queries require a valid API key via X-API-Key header"
}

With a wrong key:

{
  "error": "Invalid API key",
  "message": "The provided API key is not valid"
}

Not found (404)

{
  "error": "Lyrics not available for this track"
}

The error text depends on why no lyrics were found. This result is cached, and later requests for the same query get X-Cache-Status: NEGATIVE_HIT.

Rate limited (429)

Both rate limit tiers are exhausted. Content-Type: text/plain, Retry-After: 1, X-RateLimit-Type: exceeded:

Too Many Requests

The normal tier is exhausted and the query is not cached, so the cached tier cannot serve it. JSON, Retry-After: 60, X-RateLimit-Type: cached:

{
  "error": "Rate limit exceeded. This request requires cached data, but no cache is available for this query.",
  "message": "Please try again later or reduce your request rate."
}

Upstream error (500)

The upstream fetch failed and no cached fallback exists. The error text is the upstream error:

{
  "error": "<upstream error message>"
}

Cache-only mode (503)

The server is temporarily serving only cached lyrics and the query is not cached:

{
  "error": "Service running in cache-only mode. No cached lyrics available for this query."
}

Provider-specific endpoints

These endpoints select one provider. They take the same s, a, al and d parameters (but not videoId), and return the same 422 and rate limit responses.

{
  "lyrics": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>...",
  "provider": "ttml"
}

They differ from /getLyrics in these ways:

• The body is lyrics and provider, not ttml. There is no score.
• Every JSON response, errors included, has an X-Provider header with the provider name. JSON error bodies also have a provider field.
• Cache lookups use the exact cache key. There is no duration tolerance and no STALE fallback.
• /ttml/getLyrics builds its cache keys in a different format from /getLyrics. When you send an album or a duration, the two endpoints do not share cache entries.
• X-Auth-Mode is sent only by /ttml/getLyrics, and only when the server enforces API keys.

Edit this page on GitHub