---
title: "List transcribe jobs (for the authenticated user)"
method: GET
path: "/v1/transcribes"
---

# List transcribe jobs (for the authenticated user)

`GET /v1/transcribes`

## Request

- Base URL: `https://api.ffmpeg-micro.com`
- URL: `https://api.ffmpeg-micro.com/v1/transcribes`
- Auth: HTTP bearer

## Query parameters

- `status` 'pending' | 'processing' | 'completed' | 'failed' | 'canceled': Job lifecycle: `pending` (created, awaiting pickup) → `processing` → `completed` | `failed`; a user cancellation sets `canceled` (US spelling). Note there is no `queued` status — new jobs start as `pending`.
- `page` integer
- `limit` integer
- `order` 'created_at.desc' | 'updated_at.asc' | 'updated_at.desc'
- `since` string, date-time
- `until` string, date-time

## Response `200`

OK

- object
  - `items` Transcribe[]
    - `id` string, uuid, required
    - `status` 'pending' | 'processing' | 'completed' | 'failed' | 'canceled', required: Job lifecycle: `pending` (created, awaiting pickup) → `processing` → `completed` | `failed`; a user cancellation sets `canceled` (US spelling). Note there is no `queued` status — new jobs start as `pending`.
    - `job_type` 'transcribe'
    - `media_url` string, required: GCS URL of the source audio/video (echoed from the request)
    - `input_url` string: Same value as `media_url` (legacy field name on reads)
    - `output_format` 'srt', required: Always `srt` for transcribe jobs
    - `output_url` string, nullable: `gs://` URL of the generated SRT once `status` is `completed`. Use `/v1/transcribe/{id}/download` to obtain a signed HTTPS URL.
    - `error_message` string, nullable: Populated when status is `failed` or `canceled` ("Job canceled by user")
    - `error_category` 'processing_limit' | 'file_size' | 'quota' | 'upload' | 'storage' | 'validation' | 'processing' | 'transient' | 'unknown': Machine classification derived from error_message (generated column). Only meaningful when status is `failed`; jobs with no error carry `unknown`, never null.
    - `duration_seconds` number, nullable: Duration of the source media (drives billing — input minutes)
    - `billable_minutes` number, nullable: Billable minutes, metered per second on input duration (a 19-second job bills 0.3167). Not an integer.
    - `processing_time_seconds` number, nullable: Wall-clock processing time measured by the toolkit; null until completed
    - `queue_position` integer, nullable: Jobs waiting in the job's toolkit lane at acceptance, this one included: the accepting worker's queue length right after this job was enqueued, so 1 means it was next in line. Set once at acceptance and never updated: a rough "how far back was I", not a live counter. Once `started_at` is set the job is no longer waiting, whatever this says. Null on jobs accepted before the field existed, or when the toolkit's accept response carried no queue length.
    - `lane` 'short' | 'long' | 'heavy' | 'null', nullable: The processing lane the job runs in. Jobs with many large inputs (more than five 4K frames' worth of pixels in total) go to `heavy`, a service with more memory. Otherwise, inputs longer than two minutes (by probed length or requested output span) go to `long`; everything else is `short`. Each lane is a separate service, so nothing in one can delay a job in another. Null on jobs accepted before lanes existed.
    - `started_at` string, date-time, nullable: When the toolkit began executing the job. Set as soon as encoding starts, so null means the job is still waiting in its lane and non-null with status `processing` means it is encoding now. If that start signal was missed, it is filled from the completion or failure report. `started_at - created_at` is submission-to-start and includes the gateway's own download and probe before dispatch, so it is an upper bound on queue wait, not the wait itself.
    - `created_at` string, date-time, required
    - `updated_at` string, date-time
    - `completed_at` string, date-time, nullable
    - `user_id` string: Internal user identifier resolved from API key
  - `page` integer
  - `limit` integer
  - `total` integer

## Other responses

- `400`: Invalid page, limit, since, or until parameter
- `401`: Missing/invalid API key
- `500`: Unexpected error

---

[API](https://skmtc.dev/ffmpeg-micro/apis/ffmpeg-micro-api.md) · [All operations](https://skmtc.dev/ffmpeg-micro/apis/ffmpeg-micro-api/llms.txt) · [OpenAPI document](https://skmtc.dev/ffmpeg-micro/apis/ffmpeg-micro-api/revisions/64bb930ff345?raw)