Transcription API

List all jobs

GET https://eu1.asr.api.speechmatics.com/v2/jobs

Authentication

bearerAuth Authorization: Bearer <token>
Your API key, or a temporary key (JWT).

Query parameters

created_before string<date-time> optional: UTC Timestamp cursor for paginating request response. Filters jobs based on creation time to the nearest millisecond. Accepts up to nanosecond precision, truncating to millisecond precision. By default, the response will start with the most recent job.
limit integer≥ 1, ≤ 100 optional: Limit on the number of items returned. By default, no limit is applied.
include_deleted boolean optional: Specifies whether deleted jobs should be included in the response. Defaults to false.

Responses

application/json application/vnd.speechmatics.v2+json

jobs JobDetails[]: Document describing a job. JobConfig will be present in JobDetails returned for GET jobs/{id} request in SaaS and in Batch Appliance, but it will not be present in JobDetails returned as item in RetrieveJobsResponse in case of Batch Appliance.
created_at string<date-time>: The UTC date time the job was created.
data_name string: Name of the data file submitted for job.
text_name string optional: Name of the text file submitted to be aligned to audio.
duration integer≥ 0 optional: The file duration (in seconds). May be missing for fetch URL jobs.
id string: The unique id assigned to the job.
status enumone of: The status of the job.
"running": The job is actively running.
"done": The job completed successfully.
"rejected": The job was accepted at first, but later could not be processed by the transcriber.
"deleted": The user deleted the job.
"expired": The system deleted the job. Usually because the job was in the done state for a very long time.
config JobConfig optional: JSON object that contains various groups of job configuration parameters. Based on the value of type, a type-specific object such as transcription_config is required to be present to specify all configuration settings or parameters needed to process the job inputs as expected.

If the results of the job are to be forwarded on completion, notification_config can be provided with a list of callbacks to be made; no assumptions should be made about the order in which they will occur.

Customer specific job details or metadata can be supplied in tracking, and this information will be available where possible in the job results and in callbacks.
type JobType"transcription"
fetch_data DataFetchConfig optional
url string
auth_headers string[] optional: A list of additional headers to be added to the input fetch request when using http or https. This is intended to support authentication or authorization, for example by supplying an OAuth2 bearer token.
fetch_text DataFetchConfig optional
url string
auth_headers string[] optional: A list of additional headers to be added to the input fetch request when using http or https. This is intended to support authentication or authorization, for example by supplying an OAuth2 bearer token.
transcription_config TranscriptionConfig optional
language string: Language model to process the audio input, normally specified as an ISO language code
domain string optional: Request a specialized model based on 'language' but optimized for a particular field, e.g. 'finance' or 'medical'.
output_locale string optional: Language locale to be used when generating the transcription output, normally specified as an ISO language code
model Model"standard""enhanced""melia-1" optional: Specific model to use in transcription (previously called operating point).
operating_point OperatingPoint"standard""enhanced""melia-1" optional
additional_vocab object[]≤ 20000 items optional: List of custom words or phrases that should be recognized. Alternative pronunciations can be specified to aid recognition.
content string
sounds_like string[] optional
punctuation_overrides object optional: Control punctuation settings.
sensitivity number<float>≥ 0, ≤ 1 optional: Ranges between zero and one. Higher values will produce more punctuation. The default is 0.5.
permitted_marks string[] optional: The punctuation marks which the client is prepared to accept in transcription output, or the special value 'all' (the default). Unsupported marks are ignored. This value is used to guide the transcription process.
diarization "none" | "speaker" | "channel" optional: Specify whether speaker or channel labels are added to the transcript. The default is none.

none: no speaker or channel labels are added.

speaker: speaker attribution is performed based on acoustic matching; all input channels are mixed into a single stream for processing.

channel: multiple input channels are processed individually and collated into a single transcript.
channel_diarization_labels string[] optional: Transcript labels to use when using collating separate input channels.
enable_entities boolean optional: Include additional 'entity' objects in the transcription results (e.g. dates, numbers) and their original spoken form. These entities are interleaved with other types of results. The concatenation of these words is represented as a single entity with the concatenated written form present in the 'content' field. The entities contain a 'spoken_form' field, which can be used in place of the corresponding 'word' type results, in case a spoken form is preferred to a written form. They also contain a 'written_form', which can be used instead of the entity, if you want a breakdown of the words without spaces. They can still contain non-breaking spaces and other special whitespace characters, as they are considered part of the word for the formatting output. In case of a written_form, the individual word times are estimated and might not be accurate if the order of the words in the written form does not correspond to the order they were actually spoken (such as 'one hundred million dollars' and '$100 million').
max_delay_mode "fixed" | "flexible" optional: Whether or not to enable flexible endpointing and allow the entity to continue to be spoken.
audio_filtering_config object optional: Configuration for limiting the transcription of quiet audio.
volume_threshold number<float>≥ 0, ≤ 100 optional: Controls the lower limit of audio volume at which speech and audio events will be transcribed. If the volume limit is very low, then most sound will be passed to the speech recognition engine. Higher numbers will cut out increasing amounts of sound.
transcript_filtering_config object optional: Configuration for applying filtering to the transcription
remove_disfluencies boolean optional: If true, words that are identified as disfluencies will be removed from the transcript. If false (default), they are tagged in the transcript as 'disfluency'.
replacements object[] optional: An array of objects defining custom replacements. Each replacement contains a pair of strings: the text to find from and the text to replace it with to.
from string
to string
speaker_diarization_config object optional: Configuration for speaker diarization
prefer_current_speaker boolean optional: If true, the algorithm will prefer to stay with the current active speaker if it is a close enough match, even if other speakers may be closer. This is useful for cases where we can flip incorrectly between similar speakers during a single speaker section.
speaker_sensitivity number<float>≥ 0, ≤ 1 optional: Controls how sensitive the algorithm is in terms of keeping similar speakers separate, as opposed to combining them into a single speaker. Higher values will typically lead to more speakers, as the degree of difference between speakers in order to allow them to remain distinct will be lower. A lower value for this parameter will conversely guide the algorithm towards being less sensitive in terms of retaining similar speakers, and as such may lead to fewer speakers overall. The default is 0.5.
get_speakers boolean optional: If true, speaker identifiers will be returned at the end of transcript.
speakers SpeakersInputItem[] optional: Use this option to provide speaker labels linked to their speaker identifiers. When passed, the transcription system will tag spoken words in the transcript with the provided speaker labels whenever any of the specified speakers is detected in the audio. A maximum of 50 speakers identifiers across all speakers can be provided.
label string≥ 1 characters: Speaker label, which must not match the format used internally (e.g. S1, S2, etc)
speaker_identifiers Array<string<bytes>>≥ 1 itemsunique items
notification_config NotificationConfig[] optional
url string: The url to which a notification message will be sent upon completion of the job. The job id and status are added as query parameters, and any combination of the job inputs and outputs can be included by listing them in contents.

If contents is empty, the body of the request will be empty.

If only one item is listed, it will be sent as the body of the request with Content-Type set to an appropriate value such as application/octet-stream or application/json.

If multiple items are listed they will be sent as named file attachments using the multipart content type.

If contents is not specified, the transcript item will be sent as a file attachment named data_file, for backwards compatibility.

If the job was rejected or failed during processing, that will be indicated by the status, and any output items that are not available as a result will be omitted. The body formatting rules will still be followed as if all items were available.

The user-agent header is set to Speechmatics-API/2.0, or Speechmatics API V2 in older API versions.
contents enum[] optional: Specifies a list of items to be attached to the notification message. When multiple items are requested, they are included as named file attachments.
method "post" | "put" optional: The method to be used with http and https urls. The default is post.
auth_headers string[] optional: A list of additional headers to be added to the notification request when using http or https. This is intended to support authentication or authorization, for example by supplying an OAuth2 bearer token.
tracking TrackingData optional
title string optional: The title of the job.
reference string optional: External system reference.
tags string[] optional
details object optional: Customer-defined JSON structure.
output_config OutputConfig optional
srt_overrides object optional: Parameters that override default values of srt conversion. max_line_length: sets maximum count of characters per subtitle line including white space. max_lines: sets maximum count of lines in a subtitle section.
max_line_length integer optional
max_lines integer optional
translation_config TranslationConfig optional
target_languages string[]≤ 5 items
language_identification_config LanguageIdentificationConfig optional
expected_languages string[] optional
low_confidence_action "allow" | "reject" | "use_default_language" optional: Action to take if all of the predicted languages are below the confidence threshold
default_language string optional
summarization_config SummarizationConfig optional: Configuration options for summarization.
content_type "auto" | "informative" | "conversational" optional: Choose from three options:

conversational - Best suited for dialogues involving multiple participants, such as calls, meetings or discussions. It focuses on summarizing key points of the conversation.

informative - Recommended for more structured information delivered by one or more people, making it ideal for videos, podcasts, lectures, and presentations.

auto - Automatically selects the most appropriate content type based on an analysis of the transcript.
summary_length "brief" | "detailed"default: "brief" optional: Determines the depth of the summary:

brief - Provides a succinct summary, condensing the content into just a few sentences.

detailed - Provide a longer, structured summary. For conversational content, it includes key topics and a summary of the entire conversation. For informative content, it logically divides the audio into sections and provides a summary for each.
summary_type "paragraphs" | "bullets" optional
sentiment_analysis_config SentimentAnalysisConfig optional
topic_detection_config TopicDetectionConfig optional
topics string[] optional
auto_chapters_config AutoChaptersConfig optional
audio_events_config AudioEventsConfig optional
types string[] optional
lang string optional: Optional parameter used for backwards compatibility with v1 api
errors JobDetailError[] optional: Optional list of errors that have occurred in user interaction, for example: audio could not be fetched or notification could not be sent.
timestamp string
message string

Request

import { BatchClient } from "@speechmatics/batch-client";

const client = new BatchClient({ apiKey: "YOUR_API_KEY", appId: "my-app" });

const { jobs } = await client.listJobs({ limit: 10 });
for (const job of jobs) {
  console.log(job.id, job.status);
}

from speechmatics.batch import Client

with Client(api_key="YOUR_API_KEY") as client:
    for job in client.list_jobs(limit=10):
        print(job.id, job.status)

API_KEY="YOUR_API_KEY"

curl -L -X GET "https://eu1.asr.api.speechmatics.com/v2/jobs?limit=10" \
  -H "Authorization: Bearer ${API_KEY}"

Responses

{
  "jobs": [
    {
      "created_at": "2026-10-28T09:12:44.583Z",
      "data_name": "example.wav",
      "duration": 42,
      "id": "dlbvi9xpzf",
      "status": "done",
      "config": {
        "type": "transcription",
        "transcription_config": {
          "language": "en",
          "model": "enhanced"
        }
      }
    },
    {
      "created_at": "2026-10-27T16:03:10.112Z",
      "data_name": "interview.mp3",
      "duration": 1806,
      "id": "r9fk2m1x7q",
      "status": "running",
      "config": {
        "type": "transcription",
        "transcription_config": {
          "language": "en",
          "diarization": "speaker"
        }
      }
    }
  ]
}

{
  "code": 401,
  "error": "Permission Denied"
}

{
  "code": 422,
  "error": "limit in query must be of type int64"
}

{
  "code": 500,
  "error": "Internal Server Error"
}