> For the documentation index, fetch https://sync.so/docs/llms.txt. Append .md to a page URL for Markdown. Documentation-search MCP: https://sync.so/docs/_mcp/server.

# Get a transcription job

GET https://api.sync.so/v2/transcriptions/{id}

Returns the job status and, once `status` is `COMPLETED`, the word-level transcript. `COMPLETED` and `FAILED` are terminal; `error.code` says why a job failed.

Reference: https://sync.so/docs/api-reference/api/transcriptions-api/get

## Authentication

- `x-api-key` header (required) — API Key authentication via header

## Servers

- `https://api.sync.so` (Default, default)
- `https://dev-api.sync.so` (dev)
- `http://localhost:3001` (local)

## Request

### Path parameters

- `id` (string, required) — Transcription job id.

## Response

### 200

Transcription job retrieved successfully

- `id` (string, required) — Job id. Poll GET /v2/transcriptions/\{id} with it.
- `status` (enum, required) — Job status. COMPLETED and FAILED are terminal.
  - Allowed values: `PENDING`, `PROCESSING`, `COMPLETED`, `FAILED`
- `sourceStartMs` (integer, required) — Start of the transcribed window, in source milliseconds.
- `createdAt` (datetime, required) — When the job was created.
- `sourceVideoUrl` (string, optional) — The source video the job was created from. Null for jobs created from sourceAudioUrl.
- `sourceEndMs` (integer, optional) — End of the transcribed window, in source milliseconds. Null when the job transcribes to the end of the source.
- `transcript` (Transcript, optional) — Word-level transcript. Word timings are in milliseconds from the start of the source video, not the window. Null until status is COMPLETED.
- `speakerCount` (integer, optional) — Number of distinct speakers detected. Dialogue edits currently support a single speaker; a count above 1 completes the job but a dialogue edit of that source is unsupported. Null until status is COMPLETED.
- `difficulty` (TranscriptionDifficulty, optional) — Informational estimate of how hard the source is to edit cleanly, with the reasons behind it. Null while the job is running and for some older jobs. Do not gate behaviour on it.
- `error` (TranscriptionError, optional) — Why the job failed. Null unless status is FAILED.
- `startedAt` (datetime, optional) — When the job started processing. Null until it starts.
- `finishedAt` (datetime, optional) — When the job reached a terminal status. Null until it finishes.

## Errors

### 401 Unauthorized Error

Unauthorized - Invalid or missing authentication

- `message` (GenerationErrorMessage, required) — A message describing the error.
- `statusCode` (double, required) — The type of error that occurred.
- `errorCode` (string, optional) — Stable, machine-readable error code (e.g. project_not_found, voice_not_found, concurrency_limit_reached). Branch your error handling on this, not on the message text. The full catalog of codes with messages and suggested fixes is served unauthenticated at GET /v2/errors.
- `suggestion` (string, optional) — A suggested fix an agent can act on.
- `field` (string, optional) — The request field the error refers to, when the failure is tied to a specific field (e.g. projectId, voiceId, input[].assetId).
- `docsUrl` (string, optional) — Link to the documentation page for the failing operation.
- `requestId` (string, optional) — Present on unexpected 500 responses. Include it when contacting support so the failing request can be located directly.
- `generationId` (string, optional) — Original generation ID when available for an uncertain keyed submission. Poll this ID; do not create another action to bypass IDEMPOTENCY_OUTCOME_UNKNOWN.
- `dialogueEditSection` (DialogueEditRetimeFailureSection, optional) — For dialogue_edit_removal_too_large: the section to change, when it can be identified. Create a new dialogue edit preview before submitting again.

### 404 Not Found Error

Job not found

- `message` (GenerationErrorMessage, required) — A message describing the error.
- `statusCode` (double, required) — The type of error that occurred.
- `errorCode` (string, optional) — Stable, machine-readable error code (e.g. project_not_found, voice_not_found, concurrency_limit_reached). Branch your error handling on this, not on the message text. The full catalog of codes with messages and suggested fixes is served unauthenticated at GET /v2/errors.
- `suggestion` (string, optional) — A suggested fix an agent can act on.
- `field` (string, optional) — The request field the error refers to, when the failure is tied to a specific field (e.g. projectId, voiceId, input[].assetId).
- `docsUrl` (string, optional) — Link to the documentation page for the failing operation.
- `requestId` (string, optional) — Present on unexpected 500 responses. Include it when contacting support so the failing request can be located directly.
- `generationId` (string, optional) — Original generation ID when available for an uncertain keyed submission. Poll this ID; do not create another action to bypass IDEMPOTENCY_OUTCOME_UNKNOWN.
- `dialogueEditSection` (DialogueEditRetimeFailureSection, optional) — For dialogue_edit_removal_too_large: the section to change, when it can be identified. Create a new dialogue edit preview before submitting again.

### 500 Internal Server Error

Internal Server Error - An unexpected failure on our side. The body carries errorCode internal_error and a requestId; include the requestId when contacting support.

- `message` (GenerationErrorMessage, required) — A message describing the error.
- `statusCode` (double, required) — The type of error that occurred.
- `errorCode` (string, optional) — Stable, machine-readable error code (e.g. project_not_found, voice_not_found, concurrency_limit_reached). Branch your error handling on this, not on the message text. The full catalog of codes with messages and suggested fixes is served unauthenticated at GET /v2/errors.
- `suggestion` (string, optional) — A suggested fix an agent can act on.
- `field` (string, optional) — The request field the error refers to, when the failure is tied to a specific field (e.g. projectId, voiceId, input[].assetId).
- `docsUrl` (string, optional) — Link to the documentation page for the failing operation.
- `requestId` (string, optional) — Present on unexpected 500 responses. Include it when contacting support so the failing request can be located directly.
- `generationId` (string, optional) — Original generation ID when available for an uncertain keyed submission. Poll this ID; do not create another action to bypass IDEMPOTENCY_OUTCOME_UNKNOWN.
- `dialogueEditSection` (DialogueEditRetimeFailureSection, optional) — For dialogue_edit_removal_too_large: the section to change, when it can be identified. Create a new dialogue edit preview before submitting again.

## Types

### Transcript

A word-level transcript. Word timings are in milliseconds from the start of the source video.

- `segments` (list of TranscriptSegment, required) — The transcript segments, in order.
- `speakerCount` (integer, required) — The number of distinct speakers detected.

### TranscriptionDifficulty

Informational estimate of how hard the source is to edit cleanly, with the reasons behind it. Do not gate behaviour on it.

- `tier` (enum, required) — The overall difficulty tier.
  - Allowed values: `green`, `yellow`, `red`
- `reasons` (list of enum, required) — The reasons behind the tier.
  - Allowed values: `MULTI_SPEAKER`, `LOW_ASR_CONFIDENCE`, `LOW_SPLICE_OPPORTUNITY`, `FAST_VARIABLE_RATE`, `LOW_AUDIO_QUALITY`, `VERY_SHORT_SOURCE`, `VERY_LONG_SOURCE`, `LOW_AUDIO_BANDWIDTH`

### TranscriptionError

Why a transcription job failed. Present only when status is FAILED.

- `code` (enum, required) — Machine-readable failure code. NO_AUDIO, NO_AUDIO_TRACK and SOURCE_TOO_LONG describe the source and will not succeed on retry.
  - Allowed values: `NO_AUDIO`, `NO_AUDIO_TRACK`, `SOURCE_TOO_LONG`, `EXTRACTION_FAILED`, `PROVIDER_FAILED`, `TIMEOUT`, `UNKNOWN`
- `message` (string, required) — Human-readable summary of the failure.

### GenerationErrorMessage

A message describing the error.

### DialogueEditRetimeFailureSection

The dialogue-edit section that removes too much speech to stay in sync.

- `slotIndex` (integer, required) — Zero-based index of the section in the preview's `resultSlots`.
- `sourceStartMs` (integer, optional) — Start of the section in the source video, in absolute milliseconds.
- `sourceDurationMs` (integer, optional) — Length of the section in the source video, in milliseconds.

### TranscriptSegment

A run of words attributed to one speaker turn.

- `id` (string, required) — The segment id.
- `words` (list of TranscriptWord, required) — The words in the segment, in order.

### TranscriptWord

A single transcribed word with its timing in the source.

- `id` (string, required) — The word id. Dialogue edits name words by this id.
- `text` (string, required) — The transcribed text of the word.
- `startMs` (integer, required) — Start of the word, in milliseconds from the start of the source.
- `endMs` (integer, required) — End of the word, in milliseconds from the start of the source.

## Examples

**Response**

```json
{
  "id": "6533643b-aceb-4c40-967e-d9ba9baac39e",
  "status": "COMPLETED",
  "sourceStartMs": 0,
  "createdAt": "2024-01-15T09:30:00Z",
  "sourceVideoUrl": "https://assets.sync.so/docs/example-video.mp4",
  "sourceEndMs": 30000,
  "transcript": {
    "segments": [
      {
        "id": "seg_1",
        "words": [
          {
            "id": "w_1",
            "text": "The",
            "startMs": 120,
            "endMs": 260
          },
          {
            "id": "w_2",
            "text": "quarterly",
            "startMs": 260,
            "endMs": 820
          },
          {
            "id": "w_3",
            "text": "results",
            "startMs": 820,
            "endMs": 1240
          }
        ]
      }
    ],
    "speakerCount": 1
  },
  "speakerCount": 1,
  "difficulty": {
    "tier": "green",
    "reasons": []
  },
  "startedAt": "2024-01-15T09:30:02Z",
  "finishedAt": "2024-01-15T09:30:20Z"
}
```

**SDK Code**

```python
import requests

url = "https://api.sync.so/v2/transcriptions/6533643b-aceb-4c40-967e-d9ba9baac39e"

headers = {"x-api-key": "<apiKey>"}

response = requests.get(url, headers=headers)

print(response.json())
```

```javascript
const url = 'https://api.sync.so/v2/transcriptions/6533643b-aceb-4c40-967e-d9ba9baac39e';
const options = {method: 'GET', headers: {'x-api-key': '<apiKey>'}};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go
package main

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

func main() {

	url := "https://api.sync.so/v2/transcriptions/6533643b-aceb-4c40-967e-d9ba9baac39e"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("x-api-key", "<apiKey>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.sync.so/v2/transcriptions/6533643b-aceb-4c40-967e-d9ba9baac39e")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["x-api-key"] = '<apiKey>'

response = http.request(request)
puts response.read_body
```

```java
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.get("https://api.sync.so/v2/transcriptions/6533643b-aceb-4c40-967e-d9ba9baac39e")
  .header("x-api-key", "<apiKey>")
  .asString();
```

```php
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'https://api.sync.so/v2/transcriptions/6533643b-aceb-4c40-967e-d9ba9baac39e', [
  'headers' => [
    'x-api-key' => '<apiKey>',
  ],
]);

echo $response->getBody();
```

```csharp
using RestSharp;

var client = new RestClient("https://api.sync.so/v2/transcriptions/6533643b-aceb-4c40-967e-d9ba9baac39e");
var request = new RestRequest(Method.GET);
request.AddHeader("x-api-key", "<apiKey>");
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = ["x-api-key": "<apiKey>"]

let request = NSMutableURLRequest(url: NSURL(string: "https://api.sync.so/v2/transcriptions/6533643b-aceb-4c40-967e-d9ba9baac39e")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "GET"
request.allHTTPHeaderFields = headers

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```