> This page is for API Reference.

> Sarvam Voice Agents (Samvaad) is a voice AI agent platform for Indian languages: build, test and deploy AI calling agents on your own phone numbers, from ₹3 a minute. Start here: https://docs.sarvam.ai/voice-agents/why-voice-agents.
> For clean Markdown of any page, append `.md` to the page URL.
> For a complete documentation index, see https://docs.sarvam.ai/llms.txt. For a section index, append `/llms.txt` to any section URL (for example https://docs.sarvam.ai/voice-agents/llms.txt).
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.sarvam.ai/_mcp/server.

# Get Job

GET https://api.sarvam.ai/v2/dictate/jobs/{job_id}

Returns the state of a job and, when it is `Completed`, the result. A `Failed` job still returns `200`, with the reason in `error`.

- Poll every 5 seconds or more, or use a callback. Each read counts in the key's rate limit at the gateway: on `429`, wait for `Retry-After`.
- Results are kept for 7 days after completion. After that, this returns `404`.
- Any key of the organisation that created the job can read it.
- There is no route to list jobs, so keep the `job_id` from Create Job.

Reference: https://docs.sarvam.ai/api-reference/dictate/get-job

## Authentication

- `api-subscription-key` header (required) — API Key authentication via header
- `Authorization` header (bearer token, required) — Bearer authentication of the form `Bearer <token>`, where token is your auth token.

## Request

### Path parameters

- `job_id` (string, required) — The `job_id` returned when the job was created.

## Response

### 200

Successful Response

- `job_id` (string, required)
- `job_state` (enum, required) — - `Accepted`: saved and in the queue. - `Pending`: back in the queue after a temporary internal problem. - `Running`: a worker is processing it. - `Completed`: `result` is ready. - `Failed`: `error` tells why.
  - Allowed values: `Accepted`, `Pending`, `Running`, `Completed`, `Failed`
- `created_at` (string, required) — UTC time, RFC 3339.
- `completed_at` (string, required, nullable) — Set when the job is `Completed` or `Failed`.
- `expires_at` (string, required, nullable) — Set when the job is `Completed` or `Failed`: 7 days after completion. After this, GET returns 404.
- `error` (DictateJobError, required, nullable) — Set when the job is `Failed`.
- `result` (DictateJobResult, required, nullable) — Set when the job is `Completed`.

## Errors

### 403 Forbidden Error

Missing or wrong API key (`invalid_api_key_error`). The gateway answers before Dictate does, with the same error shape.

- `error` (V2ErrorObject, required)

### 404 Not Found Error

Job not found (`not_found_error`): the ID does not exist, belongs to another organisation, was deleted or has expired.

- `error` (V2ErrorObject, required)

### 405 Method Not Allowed Error

Wrong HTTP method for this path (`invalid_request_error`). This path takes `GET` and `DELETE`.

- `error` (V2ErrorObject, required)

### 429 Too Many Requests Error

Your key is over its rate limit (`rate_limit_exceeded_error`). The gateway answers before Dictate does, with the usual error shape. Retry after the number of seconds in the `Retry-After` header. Job reads count toward the limit.

- `error` (V2ErrorObject, required)

### 500 Internal Server Error

Unexpected problem (`internal_server_error`). Retry once, and report it with the `x-request-id` header if it repeats.

- `any`

### 503 Service Unavailable Error

Has the header `Retry-After: 1`. - `service_overloaded`: Dictate is at a capacity limit. Retry after `Retry-After`, with backoff. - `model_overloaded`: speech recognition is overloaded or not available. Retry with backoff. - `service_unavailable`: the route is not available. Do not retry.

- `any`

## Types

### DictateJobError

- `code` (string, required) — Why the job failed. - `invalid_audio_url`: the URL failed the URL rules when Dictate downloaded it, or DNS failed. Correct the URL and make a new job. - `fetch_failed`: the download failed (an HTTP error, too large, empty, too many redirects or a network error). - `invalid_audio`: the file has no audio that can be read. - `audio_too_long`: longer than 3,600 s. Split the file. - `asr_error`: speech recognition failed for a piece of the audio. Make a new job. - `processing_failed`: the job failed 3 times because of an internal problem. Make a new job later. - `expired`: the job did not finish in 6 hours. Make a new job later. - `internal_error`: internal problem. Make a new job later.
- `message` (string, required) — A description for people. Use `code` in your program.

### DictateJobResult

- `model` (string, required) — The snapshot that made this result, for example `dictate-v1-2026-11-04` or `dictate-v1-2026-11-05`.
- `transcript` (string, required) — The full raw transcript.
- `text` (string, required) — The full finished text: the texts of the sections, joined by a blank line.
- `language_code` (string, required, nullable) — The main language of the file.
- `degraded` (enum, required, nullable) — `null` when every section was finished. Otherwise the reason of the first degraded section; check `degraded` on each item in `sections` to see which parts are raw text.
  - Allowed values: `llm_timeout`, `llm_error`, `llm_guard_failed`, `llm_context_limit`, `asr_error`, `asr_timeout`
- `corrections` (list of DictateCorrection, required) — All corrections in the job.
- `segments` (list of DictateSegment, required) — The pieces of audio that were recognised.
- `sections` (list of DictateSection, required) — The parts of text that were finished one at a time.
- `usage` (DictateUsage, required) — A job bills the whole file less the time of its degraded sections.
- `output` (DictateOutput, optional) — Present only when you sent `output_rules`.

### V2ErrorObject

- `message` (string, optional)
- `code` (string, optional) — Machine-readable code, e.g. `invalid_request_error`, `not_found_error`.
- `request_id` (string, optional)
- `param` (string, optional, nullable) — Present when a field was named.
- `spend_limits` (map from string to any, optional, nullable) — Present only on a 429 from an exhausted seat budget.

### DictateCorrection

A change that Dictate made from your vocabulary or reference. It is listed when the finished text has the term's exact spelling where a word matched it, including a change of capital letters and a term with an apostrophe suffix ("Zentrix's"). It does not list changes that the model makes alone (including those from `context.text`), punctuation, capital letters in words that are not your terms, a term inside an email address or a URL (except at the start of the address, followed by a hyphen or apostrophe), or a term with a suffix joined without an apostrophe.

- `heard` (string, required) — What speech recognition wrote.
- `wrote` (string, required) — What the finished text has.
- `source` (enum, required) — Whether the term came from `vocabulary` or from `context.reference`.
  - Allowed values: `vocabulary`, `reference`

### DictateSegment

A piece of audio cut at a pause, at most 29.5 s long. Not a word timing or a speaker turn.

- `index` (integer, required) — Position, from 0.
- `start_s` (double, required) — Start in the audio, in seconds.
- `end_s` (double, required) — End in the audio, in seconds.
- `transcript` (string, required) — Raw text of this piece. Can be empty; a segment with an empty `transcript` can be in no section.

### DictateSection

A part of the text that was finished on its own: up to about 2,000 English words (fewer in Indian scripts), cut at a sentence end, with about 60 words of the text around it as context. A `style.rules` request that needs the whole recording gives one result for each section; for one result from the whole recording, use `output_rules`.

- `index` (integer, required) — Position, from 0.
- `start_s` (double, required) — Start in the audio, in seconds.
- `end_s` (double, required) — End in the audio, in seconds.
- `source_start_byte` (integer, required) — Start of the part of `transcript` that this section finished, in UTF-8 bytes.
- `source_end_byte` (integer, required) — End of that part of `transcript`, in UTF-8 bytes, not included.
- `segment_indices` (list of integer, required) — The segments in this section.
- `text` (string, required) — The finished text of this section.
- `corrections` (list of DictateCorrection, required) — Corrections in this section.
- `degraded` (enum, required, nullable) — `null` when this section was finished. Otherwise the reason, and the section has raw text.
  - Allowed values: `llm_timeout`, `llm_error`, `llm_guard_failed`, `llm_context_limit`, `asr_error`, `asr_timeout`

### DictateUsage

Billed: audio that was recognised and finished, silence included. Not billed: a failed call or job, a degraded clip, and the degraded sections of a job. A repeated request is billed again. With `output_rules`, the output's tokens are included in the token counts here and also shown in `output.usage`.

- `audio_duration_s` (double, required) — Audio length in seconds, to 3 decimals. For a clip or a job, the whole file, including silence. A degraded clip still shows the clip length, but is not billed.
- `words` (integer, required) — Words in the raw transcript.
- `llm_input_tokens` (integer, required, nullable) — Tokens sent to the finishing model. `null` if the model did not report them.
- `llm_output_tokens` (integer, required, nullable) — Tokens from the finishing model. `null` if the model did not report them.

### DictateOutput

The output made from the whole recording with `output_rules`.

- `text` (string, required, nullable) — The output as written. JSON comes back as a string: parse it yourself. In a JSON output, a string value that is only the word "null" (any case, spaces around it) comes back as JSON `null`; nothing else in the output is changed. `null` when the call gave no usable text (see `degraded`).
- `degraded` (enum, required, nullable) — `null` for a complete output. Otherwise the reason it is not complete.
  - Allowed values: `llm_timeout`, `llm_error`, `llm_context_limit`, `llm_length`, `asr_incomplete`
- `usage` (DictateOutputUsage, required)

### DictateOutputUsage

- `llm_input_tokens` (integer, required, nullable) — Tokens sent to the model for this output.
- `llm_output_tokens` (integer, required, nullable) — Tokens the model wrote for this output.

## Examples

### A completed job

**Response**

```json
{
  "job_id": "f30e5f77-5c5c-47ab-9ea2-31088c340851",
  "job_state": "Completed",
  "created_at": "2026-11-07T12:55:29Z",
  "completed_at": "2026-11-07T12:55:30Z",
  "expires_at": "2026-11-14T12:55:30Z",
  "error": null,
  "result": {
    "model": "dictate-v1-2026-11-04",
    "transcript": "Please open a ticket with Zentrix support. The invoice number is 4567 and the amount is 23500 rupees.",
    "text": "Please open a ticket with Zentrix Support. The invoice number is 4567 and the amount is ₹23,500.",
    "language_code": "en-IN",
    "degraded": null,
    "corrections": [
      {
        "heard": "Zentrix support",
        "wrote": "Zentrix Support",
        "source": "vocabulary"
      }
    ],
    "segments": [
      {
        "index": 0,
        "start_s": 0,
        "end_s": 8.357,
        "transcript": "Please open a ticket with Zentrix support. The invoice number is 4567 and the amount is 23500 rupees."
      }
    ],
    "sections": [
      {
        "index": 0,
        "start_s": 0,
        "end_s": 8.357,
        "source_start_byte": 0,
        "source_end_byte": 101,
        "segment_indices": [
          0
        ],
        "text": "Please open a ticket with Zentrix Support. The invoice number is 4567 and the amount is ₹23,500.",
        "corrections": [
          {
            "heard": "Zentrix support",
            "wrote": "Zentrix Support",
            "source": "vocabulary"
          }
        ],
        "degraded": null
      }
    ],
    "usage": {
      "audio_duration_s": 8.357,
      "words": 18,
      "llm_input_tokens": 5749,
      "llm_output_tokens": 52
    },
    "output": {
      "text": "{\"invoice_number\": \"4567\", \"team\": \"Zentrix Support\"}",
      "degraded": null,
      "usage": {
        "llm_input_tokens": 346,
        "llm_output_tokens": 21
      }
    }
  }
}
```

**SDK Code**

```python A completed job
from sarvamai import SarvamAI

client = SarvamAI(api_subscription_key="YOUR_SARVAM_API_KEY")

import time

while True:
    job = client.dictate.jobs.get(job_id="f30e5f77-5c5c-47ab-9ea2-31088c340851")
    if job.job_state in ("Completed", "Failed"):
        break
    time.sleep(5)  # poll every 5 s or more, or use a callback

if job.job_state == "Completed":
    print(job.result.text)
else:
    print(job.error.code, job.error.message)

```

```typescript A completed job
import { SarvamAIClient } from "sarvamai";

const client = new SarvamAIClient({ apiSubscriptionKey: process.env.SARVAM_API_KEY });

let job;
do {
  job = await client.dictate.jobs.get("f30e5f77-5c5c-47ab-9ea2-31088c340851");
  if (job.job_state === "Completed" || job.job_state === "Failed") break;
  await new Promise((resolve) => setTimeout(resolve, 5000)); // poll every 5 s or more, or use a callback
} while (true);

if (job.job_state === "Completed") console.log(job.result?.text);
else console.log(job.error?.code, job.error?.message);

```

```go A completed job
package main

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

func main() {

	url := "https://api.sarvam.ai/v2/dictate/jobs/f30e5f77-5c5c-47ab-9ea2-31088c340851"

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

	req.Header.Add("api-subscription-key", "<apiSubscriptionKey>")

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

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

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

}
```

```ruby A completed job
require 'uri'
require 'net/http'

url = URI("https://api.sarvam.ai/v2/dictate/jobs/f30e5f77-5c5c-47ab-9ea2-31088c340851")

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

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

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

```java A completed job
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.get("https://api.sarvam.ai/v2/dictate/jobs/f30e5f77-5c5c-47ab-9ea2-31088c340851")
  .header("api-subscription-key", "<apiSubscriptionKey>")
  .asString();
```

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

$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'https://api.sarvam.ai/v2/dictate/jobs/f30e5f77-5c5c-47ab-9ea2-31088c340851', [
  'headers' => [
    'api-subscription-key' => '<apiSubscriptionKey>',
  ],
]);

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

```csharp A completed job
using RestSharp;

var client = new RestClient("https://api.sarvam.ai/v2/dictate/jobs/f30e5f77-5c5c-47ab-9ea2-31088c340851");
var request = new RestRequest(Method.GET);
request.AddHeader("api-subscription-key", "<apiSubscriptionKey>");
IRestResponse response = client.Execute(request);
```

```swift A completed job
import Foundation

let headers = ["api-subscription-key": "<apiSubscriptionKey>"]

let request = NSMutableURLRequest(url: NSURL(string: "https://api.sarvam.ai/v2/dictate/jobs/f30e5f77-5c5c-47ab-9ea2-31088c340851")! 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()
```

### A failed job

**Response**

```json
{
  "job_id": "4bef2223-64ef-4857-8380-1f9c094baef7",
  "job_state": "Failed",
  "created_at": "2026-11-07T12:55:33Z",
  "completed_at": "2026-11-07T12:55:33Z",
  "expires_at": "2026-11-14T12:55:33Z",
  "error": {
    "code": "fetch_failed",
    "message": "The audio could not be downloaded: the server answered 404."
  },
  "result": null
}
```

**SDK Code**

```python A failed job
import requests

url = "https://api.sarvam.ai/v2/dictate/jobs/4bef2223-64ef-4857-8380-1f9c094baef7"

headers = {"api-subscription-key": "<apiSubscriptionKey>"}

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

print(response.json())
```

```javascript A failed job
const url = 'https://api.sarvam.ai/v2/dictate/jobs/4bef2223-64ef-4857-8380-1f9c094baef7';
const options = {method: 'GET', headers: {'api-subscription-key': '<apiSubscriptionKey>'}};

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

```go A failed job
package main

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

func main() {

	url := "https://api.sarvam.ai/v2/dictate/jobs/4bef2223-64ef-4857-8380-1f9c094baef7"

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

	req.Header.Add("api-subscription-key", "<apiSubscriptionKey>")

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

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

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

}
```

```ruby A failed job
require 'uri'
require 'net/http'

url = URI("https://api.sarvam.ai/v2/dictate/jobs/4bef2223-64ef-4857-8380-1f9c094baef7")

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

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

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

```java A failed job
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.get("https://api.sarvam.ai/v2/dictate/jobs/4bef2223-64ef-4857-8380-1f9c094baef7")
  .header("api-subscription-key", "<apiSubscriptionKey>")
  .asString();
```

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

$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'https://api.sarvam.ai/v2/dictate/jobs/4bef2223-64ef-4857-8380-1f9c094baef7', [
  'headers' => [
    'api-subscription-key' => '<apiSubscriptionKey>',
  ],
]);

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

```csharp A failed job
using RestSharp;

var client = new RestClient("https://api.sarvam.ai/v2/dictate/jobs/4bef2223-64ef-4857-8380-1f9c094baef7");
var request = new RestRequest(Method.GET);
request.AddHeader("api-subscription-key", "<apiSubscriptionKey>");
IRestResponse response = client.Execute(request);
```

```swift A failed job
import Foundation

let headers = ["api-subscription-key": "<apiSubscriptionKey>"]

let request = NSMutableURLRequest(url: NSURL(string: "https://api.sarvam.ai/v2/dictate/jobs/4bef2223-64ef-4857-8380-1f9c094baef7")! 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()
```