> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lyrcs.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# GET /jobs/[id]

> Retrieve the status and results of a transcription job

## 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       | Meaning                                                                                        |
| ------------ | ---------------------------------------------------------------------------------------------- |
| `processing` | Transcription or alignment is still running                                                    |
| `complete`   | Results are ready                                                                              |
| `failed`     | Processing failed — transcript could not be generated, or alignment timed out after 10 minutes |

<Tip>
  Poll every 10 seconds with a 3-minute timeout. Jobs typically complete in 60–90 seconds depending on audio duration and pipeline mode.
</Tip>

## Response shapes

### Processing

```json theme={null}
{
  "job_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "processing",
  "language": "Tamil",
  "align_requested": true,
  "word_align_requested": true,
  "created_at": "2024-01-01T00:00:00.000Z",
  "completed_at": null
}
```

### Complete — align=true, word\_align=true (default)

```json theme={null}
{
  "job_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "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"
    }
  }
}
```

<Note>
  `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`.
</Note>

### Complete — align=false

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

```json theme={null}
{
  "job_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "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

```json theme={null}
{
  "job_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "failed",
  "language": "Tamil",
  "align_requested": true,
  "word_align_requested": true,
  "created_at": "2024-01-01T00:00:00.000Z",
  "completed_at": null,
  "error": "processing_failed"
}
```

## Additional fields

### Review fields

Present when `review=true` was passed at submission:

```json theme={null}
{
  "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_url` is `null` until alignment completes and the token is generated. `review_approved_at` is `null` until the artist approves.

### Audio URL field

Present when the job was submitted via `audio_url` mode:

```json theme={null}
{
  "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                                   |

## Examples

<CodeGroup>
  ```bash curl theme={null}
  curl https://lyrcs.ai/api/v1/jobs/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
    -H "Authorization: Bearer $LYRCS_API_KEY"
  ```

  ```javascript Node.js theme={null}
  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);
  ```

  ```python Python theme={null}
  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"))
  ```
</CodeGroup>