GET /jobs/[id] - lyrcs.ai

Endpoint

GET https://lyrcs.ai/api/v1/jobs/{job_id}

Returns the current status of a job and, once complete, the full results including transcript, transliteration, translation, and download URLs for LRC/SRT files.

Job status values

Status	Terminal?	Meaning
`processing`	No	Still running. Keep polling.
`complete`	Yes	Results are ready
`failed`	Yes	The pipeline recorded a failure. See the `error` object for which stage and why.

complete and failed are both terminal — a job never leaves either state on its own, and never moves from failed back to complete. Once you see one of them you can stop polling. The single exception is your own request: calling POST /jobs/{id}/align on a transcript-only job returns it to processing while the timings are produced. Nothing we do server-side will move a job out of complete. failed is only ever returned when the pipeline actually recorded a failure. It is never inferred from how long a job has been running, so a slow job is processing, not failed.

Stage

Alongside status, every response carries a finer-grained stage so you can watch a job advance without inferring progress from elapsed time.

Stage	Meaning
`transcribing`	Audio is being transcribed
`awaiting_review`	Held at the transcript gate, waiting for a human
`aligning`	Transcript is ready; timestamps are being generated
`done`	Everything requested has been produced
`failed`	See the `error` object

A job submitted with align=false goes straight from transcribing to done. awaiting_review appears only for review_stage: "transcript" jobs, and means no machine work is queued — the job will not advance until someone approves it. A job held at the aligned gate reports done instead, because its pipeline work really has finished; use review_approved_at to tell whether a human has signed off.

How long jobs take

Measured end to end on production traffic, a 3-minute track takes roughly 90–130 seconds of processing — about 0.4–0.8× the audio duration. Longer tracks and batches under load take longer.

Do not set a client-side timeout of a few minutes and treat expiry as failure. A job can legitimately stay in processing for up to 15 minutes — the pipeline itself allows 10 minutes for transcription and a further 5 for alignment before it gives up and records a failure.If a job genuinely fails or stalls, the API tells you so by returning failed. You do not need your own timeout to detect it, and adding one will make healthy jobs look broken.

Prefer webhooks over polling. Webhooks only fire on terminal states, so there is no in-flight ambiguity to interpret. If you do poll, every 10–15 seconds is plenty.

Response shapes

Processing

{
  "job_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "external_id": "CATALOG_76007488",
  "status": "processing",
  "stage": "aligning",
  "language": "Tamil",
  "align_requested": true,
  "word_align_requested": true,
  "created_at": "2024-01-01T00:00:00.000Z",
  "transcript_completed_at": "2024-01-01T00:00:38.000Z",
  "completed_at": null,
  "second_opinion": null,
  "alignment": null
}

transcript_completed_at is stamped when the transcript is ready, which is before alignment finishes. completed_at means the whole job is done. Use status rather than either timestamp to decide whether a job has finished.

Complete — align=true, word_align=true (default)

{
  "job_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "external_id": "CATALOG_76007488",
  "status": "complete",
  "language": "Tamil",
  "align_requested": true,
  "word_align_requested": true,
  "created_at": "2024-01-01T00:00:00.000Z",
  "completed_at": "2024-01-01T00:01:32.000Z",
  "duration_seconds": 214,
  "studio_url": "https://lyrcs.ai/studio/a1b2c3d4-...",
  "results": {
    "transcript": "நான் உன்னை நேசிக்கிறேன்\nதெரியாமல் போனேன்...",
    "transliteration": "Naan unnai nesikirein\nTheriyaamal ponein...",
    "translation": "I love you\nI didn't know...",
    "cultural_notes": null,
    "downloads": {
      "lrc_original": "https://lyrcs.ai/api/v1/jobs/a1b2c3d4-.../download/lrc/original",
      "lrc_transliterated": "https://lyrcs.ai/api/v1/jobs/a1b2c3d4-.../download/lrc/transliterated",
      "srt_original": "https://lyrcs.ai/api/v1/jobs/a1b2c3d4-.../download/srt/original",
      "srt_transliterated": "https://lyrcs.ai/api/v1/jobs/a1b2c3d4-.../download/srt/transliterated",
      "words_original": "https://lyrcs.ai/api/v1/jobs/a1b2c3d4-.../download/words/original",
      "words_transliterated": "https://lyrcs.ai/api/v1/jobs/a1b2c3d4-.../download/words/transliterated"
    }
  },
  "second_opinion": null,
  "alignment": {
    "method": "forced",
    "coverage": 0.998,
    "line_flags": []
  }
}

words_original and words_transliterated are only present when word_align_requested: true and alignment is complete. Jobs submitted with word_align=false include only lrc_* and srt_* in downloads.

Complete — align=false

When align=false was passed at submission, downloads is omitted from the response.

{
  "job_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "external_id": "CATALOG_76007488",
  "status": "complete",
  "language": "Telugu",
  "align_requested": false,
  "word_align_requested": true,
  "created_at": "2024-01-01T00:00:00.000Z",
  "completed_at": "2024-01-01T00:01:02.000Z",
  "duration_seconds": 187,
  "studio_url": "https://lyrcs.ai/studio/a1b2c3d4-...",
  "results": {
    "transcript": "...",
    "transliteration": "...",
    "translation": "...",
    "cultural_notes": null
  }
}

Failed

{
  "job_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "external_id": "CATALOG_76007488",
  "status": "failed",
  "stage": "failed",
  "language": "Tamil",
  "align_requested": true,
  "word_align_requested": true,
  "created_at": "2024-01-01T00:00:00.000Z",
  "transcript_completed_at": null,
  "completed_at": null,
  "error": {
    "stage": "transcription",
    "message": "Transcript did not appear within 600s of job creation",
    "failed_at": "2024-01-01T00:10:04.000Z"
  }
}

error.stage is the pipeline stage that failed — transcription or alignment. A job that failed at alignment still has a usable transcript in results; one that failed at transcription has nothing.

Additional fields

Review fields

Present when review=true was passed at submission:

{
  "review_required": true,
  "review_url": "https://lyrcs.ai/review/a1b2c3d4-...?token=...",
  "review_expires_at": "2024-01-02T00:00:00.000Z",
  "review_approved_at": null,
  "review_delivery": "both"
}

review_url is null until the job reaches its gate and the token is generated — and permanently null when the job was submitted with review_delivery: "api". review_approved_at is null until someone approves.

The review block

Present only while the job is held, and gone once it is approved. It carries the lyrics the reviewer is being asked to accept, as an array of lines:

{
  "review": {
    "stage": "transcript",
    "delivery": "api",
    "lines": [
      {
        "index": 0,
        "text": "…",
        "transliteration": "…",
        "timestamp": null,
        "flagged": false
      }
    ]
  }
}

Field	Meaning
`stage`	`"transcript"` or `"aligned"` — which gate this is
`delivery`	`"both"`, `"api"` or `"link"`
`lines[].timestamp`	`[mm:ss.xx]`, or `null` at the transcript gate where alignment has not run
`lines[].flagged`	This line’s audio does not match its words. Always `false` at the transcript gate

This exists because results is only filled once a job is complete, and a held job is not — so without it there is no way to read the lyrics you are being asked to approve. It is what makes it possible to run the review inside your own product: see Running Review In Your Own Product, and POST /jobs/{id}/approve for approving one. The existing results.transcript string is unchanged; this is additive.

second_opinion and alignment

Present on every response. Both are null when the corresponding check did not run — see Quality Signals for the full field reference.

{
  "second_opinion": {
    "total_lines": 59,
    "agreed_lines": 47,
    "match_ratio": 0.79,
    "suggestions": [],
    "hidden_count": 0
  },
  "alignment": {
    "method": "forced",
    "coverage": 0.998,
    "line_flags": []
  }
}

null means the check did not run. An empty suggestions array means it ran and agreed with every line — the opposite signal. Do not collapse the two into a single falsy test.

second_opinion is available as soon as the transcript is, so it is readable while a job is still aligning. alignment is null until alignment completes, and on jobs submitted with align=false.

external_id

Present on all jobs. Contains the value passed at submission, or null if not provided.

{
  "external_id": "CATALOG_76007488"
}

Use this to map a job back to a track in your own system without maintaining a separate job_id → track lookup.

end_user

Present when end_user was supplied at submission, absent otherwise.

{
  "end_user": {
    "id": "2fc0df07-…",
    "external_id": "cust_8842",
    "email": "artist@example.com",
    "name": "Asha R."
  }
}

List rows carry id and external_id only. Either can be used with GET /v1/jobs?end_user_id=.

Audio URL field

Present when the job was submitted via audio_url mode:

{
  "audio_url": "https://cdn.example.com/songs/song-123.mp3"
}

studio_url

A link to the lyrcs.ai Studio where the transcript can be edited and reviewed. Requires a lyrcs.ai user account to view. Not intended for end-users — this is an internal review tool for distributors.

Results fields

Field	Type	Notes
`transcript`	string	Original lyrics in the source script
`transliteration`	string	Phonetic romanisation of the lyrics
`translation`	string	English translation
`cultural_notes`	string \| null	Contextual notes on cultural references, idioms, or wordplay. May be null if none are detected.
`downloads`	object	Present only when `align_requested: true` and job is complete

Top-level quality fields

Field	Type	Notes
`second_opinion`	object \| null	An independent listener’s read of the transcript. `null` means not checked. See Quality Signals.
`alignment`	object \| null	How the timings were produced, and which lines look suspect. `null` until alignment completes.

Examples

curl https://lyrcs.ai/api/v1/jobs/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "Authorization: Bearer $LYRCS_API_KEY"

async function waitForJob(jobId, apiKey, { intervalMs = 10000, timeoutMs = 180000 } = {}) {
  const deadline = Date.now() + timeoutMs;

  while (Date.now() < deadline) {
    const res = await fetch(`https://lyrcs.ai/api/v1/jobs/${jobId}`, {
      headers: { Authorization: `Bearer ${apiKey}` },
    });

    if (!res.ok) throw new Error(`HTTP ${res.status}`);
    const job = await res.json();

    if (job.status === "complete") return job;
    if (job.status === "failed") throw new Error(`Job failed: ${jobId}`);

    await new Promise((r) => setTimeout(r, intervalMs));
  }

  throw new Error("Job timed out");
}

const job = await waitForJob("a1b2c3d4-...", process.env.LYRCS_API_KEY);
console.log("Transcript:", job.results.transcript);
console.log("LRC URL:", job.results.downloads?.lrc_original);

import os, time, requests

def wait_for_job(job_id, api_key, interval=10, timeout=180):
    headers = {"Authorization": f"Bearer {api_key}"}
    deadline = time.time() + timeout

    while time.time() < deadline:
        r = requests.get(
            f"https://lyrcs.ai/api/v1/jobs/{job_id}",
            headers=headers,
        )
        r.raise_for_status()
        job = r.json()

        if job["status"] == "complete":
            return job
        if job["status"] == "failed":
            raise RuntimeError(f"Job failed: {job_id}")

        time.sleep(interval)

    raise TimeoutError("Job timed out")

job = wait_for_job("a1b2c3d4-...", os.environ["LYRCS_API_KEY"])
print("Transcript:", job["results"]["transcript"])
print("LRC URL:", job["results"].get("downloads", {}).get("lrc_original"))

​Endpoint

​Job status values

​Stage

​How long jobs take

​Response shapes

​Processing

​Complete — align=true, word_align=true (default)

​Complete — align=false

​Failed

​Additional fields

​Review fields

​The review block

​second_opinion and alignment

​external_id

​end_user

​Audio URL field

​studio_url

​Results fields

​Top-level quality fields

​Examples

Endpoint

Job status values

Stage

How long jobs take

Response shapes

Processing

Complete — align=true, word_align=true (default)

Complete — align=false

Failed

Additional fields

Review fields

The review block

second_opinion and alignment

external_id

end_user

Audio URL field

studio_url

Results fields

Top-level quality fields

Examples