Runs

The unit of work, the row you poll, the thing a webhook is about.

POST `/v1/runs`

Submit a run. Creates a run from one of the three source shapes. A YouTube run is queued; an upload or recording run is receiving until its upload completes. A run served from the cached lane comes back done in this very response with status 200, because no work was created.

Scope: runs:write · accepts Idempotency-Key · Per key, 10 per minute (burst 20) — submission spends GPU seconds.

Parameters

Name	In	Type	Notes
`Idempotency-Key`	header	`string`	A value you will not reuse by accident — a UUID. A repeat within 24 hours returns the original response with its original status code (07 §3).

Request body

Field	Type	Required	Notes
`source`	`object \| object \| object`	yes	Exactly one of the three shapes. Two, or none, is 400 invalid_request.
`name_speakers`	`boolean`		Default true. What is asked for; a single-speaker recording skips naming and says so in the step detail.
`requested_language`	`string \| null`		Pin ASR to a language. null (the default) is auto-detect. A pinned language bypasses the cached lane.
`force`	`boolean`		Default false. true skips the cached lane and runs the engine — "transcribe it again" is a real request.
`idempotency_key`	`string \| null`		An alternative to the header. If both are present and differ, 400 invalid_request.

{
  "source": {
    "type": "youtube",
    "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ"
  },
  "name_speakers": true,
  "requested_language": null,
  "force": false,
  "idempotency_key": null
}

Responses

201 — The run was created.

Field	Type	Required	Notes
`id`	`uuid`	yes
`source_type`	`SourceType`	yes
`source_url`	`uri \| null`		Always null for upload and recording.
`source_upload_id`	`uuid \| null`		Always null for youtube; null after the upload row is deleted.
`title`	`string \| null`		null until acquisition learns it. Never invented.
`author_name`	`string \| null`
`author_url`	`uri \| null`
`description`	`string \| null`
`published_on`	`date \| null`		A bare calendar date.
`duration_seconds`	`number \| null`		null until normalize establishes it.
`thumbnail_url`	`uri \| null`
`status`	`RunStatus`	yes
`lane`	`Lane`		null until a lane takes it. modal_pending is a guard value, not a lane.
`engine`	`string \| null`		A human string ("whisperx large-v2"), not an enumeration. Do not branch on it.
`current_step`	`Step \| null`
`step_log`	`StepEntry[]`	yes
`language`	`string \| null`		BCP-47-ish; null until ASR detects it.
`requested_language`	`string \| null`
`name_speakers`	`boolean`	yes	What was asked for, not what happened.
`segments`	`Segment[] \| null`		null until status is done — "not yet", never "there is none". Never present in GET /v1/runs or in a webhook body.
`segment_count`	`integer \| null`
`speaker_count`	`integer \| null`		0 is a real value: diarization produced nothing.
`word_count`	`integer \| null`
`speaker_labels`	`object (free) \| null`		Keyed by speaker id (SPEAKER_00, …). null until done, and on a done run where nothing was named.
`cached_from_run_id`	`uuid \| null`		Set only when lane is cached.
`media_fingerprint`	`string \| null`		The canonical video id, or the media sha256.
`error`	`string \| null`		A sentence for a person. Programs branch on error_class.
`error_class`	`ErrorClass \| null`
`retry_after`	`date-time \| null`		Set on error_class premiere: when to submit a NEW run.
`idempotency_key`	`string \| null`
`created_at`	`date-time`	yes
`updated_at`	`date-time`	yes
`completed_at`	`date-time \| null`		Non-null on every terminal status.
`transcript_url`	`uri \| null`		Derived. The absolute GET /v1/runs/{id}/transcript URL; null unless done.
`expected_steps`	`Step[] \| null`		Derived. null while lane is null or modal_pending — draw no checklist.
`seconds_until_modal`	`integer \| null`		Derived. null unless queued with no lane and the countdown is running.
`live_workers`	`object \| null`		Derived. null unless the countdown is running.
`worker_label`	`string \| null`		Derived. The machine's display label; null unless a fleet worker holds the run. claimed_by is never sent.
`machine_quiet`	`boolean`	yes	Derived, never null. True only for a fleet run whose worker has stopped heartbeating; always false for modal.

{
  "id": "0195c8e4-8d02-7c19-b3e7-5a1f9d20c68b",
  "source_type": "youtube",
  "source_url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
  "source_upload_id": null,
  "title": null,
  "author_name": null,
  "author_url": null,
  "description": null,
  "published_on": null,
  "duration_seconds": null,
  "thumbnail_url": null,
  "status": "queued",
  "lane": null,
  "engine": null,
  "current_step": null,
  "step_log": [],
  "language": null,
  "requested_language": null,
  "name_speakers": true,
  "segments": null,
  "segment_count": null,
  "speaker_count": null,
  "word_count": null,
  "speaker_labels": null,
  "cached_from_run_id": null,
  "media_fingerprint": "dQw4w9WgXcQ",
  "error": null,
  "error_class": null,
  "retry_after": null,
  "idempotency_key": "4f0a9e21-59f2-4d64-8e18-7d9b0b1c66aa",
  "created_at": "2026-03-11T18:04:11Z",
  "updated_at": "2026-03-11T18:04:11Z",
  "completed_at": null,
  "transcript_url": null,
  "expected_steps": null,
  "seconds_until_modal": 79,
  "live_workers": {
    "count": 2,
    "kind": "utility"
  },
  "worker_label": null,
  "machine_quiet": false
}

200 — Served from the cached lane — done already, lane cached, cached_from_run_id naming the source. Or an idempotent repeat of a cached submission.

Field	Type	Required	Notes
`id`	`uuid`	yes
`source_type`	`SourceType`	yes
`source_url`	`uri \| null`		Always null for upload and recording.
`source_upload_id`	`uuid \| null`		Always null for youtube; null after the upload row is deleted.
`title`	`string \| null`		null until acquisition learns it. Never invented.
`author_name`	`string \| null`
`author_url`	`uri \| null`
`description`	`string \| null`
`published_on`	`date \| null`		A bare calendar date.
`duration_seconds`	`number \| null`		null until normalize establishes it.
`thumbnail_url`	`uri \| null`
`status`	`RunStatus`	yes
`lane`	`Lane`		null until a lane takes it. modal_pending is a guard value, not a lane.
`engine`	`string \| null`		A human string ("whisperx large-v2"), not an enumeration. Do not branch on it.
`current_step`	`Step \| null`
`step_log`	`StepEntry[]`	yes
`language`	`string \| null`		BCP-47-ish; null until ASR detects it.
`requested_language`	`string \| null`
`name_speakers`	`boolean`	yes	What was asked for, not what happened.
`segments`	`Segment[] \| null`		null until status is done — "not yet", never "there is none". Never present in GET /v1/runs or in a webhook body.
`segment_count`	`integer \| null`
`speaker_count`	`integer \| null`		0 is a real value: diarization produced nothing.
`word_count`	`integer \| null`
`speaker_labels`	`object (free) \| null`		Keyed by speaker id (SPEAKER_00, …). null until done, and on a done run where nothing was named.
`cached_from_run_id`	`uuid \| null`		Set only when lane is cached.
`media_fingerprint`	`string \| null`		The canonical video id, or the media sha256.
`error`	`string \| null`		A sentence for a person. Programs branch on error_class.
`error_class`	`ErrorClass \| null`
`retry_after`	`date-time \| null`		Set on error_class premiere: when to submit a NEW run.
`idempotency_key`	`string \| null`
`created_at`	`date-time`	yes
`updated_at`	`date-time`	yes
`completed_at`	`date-time \| null`		Non-null on every terminal status.
`transcript_url`	`uri \| null`		Derived. The absolute GET /v1/runs/{id}/transcript URL; null unless done.
`expected_steps`	`Step[] \| null`		Derived. null while lane is null or modal_pending — draw no checklist.
`seconds_until_modal`	`integer \| null`		Derived. null unless queued with no lane and the countdown is running.
`live_workers`	`object \| null`		Derived. null unless the countdown is running.
`worker_label`	`string \| null`		Derived. The machine's display label; null unless a fleet worker holds the run. claimed_by is never sent.
`machine_quiet`	`boolean`	yes	Derived, never null. True only for a fleet run whose worker has stopped heartbeating; always false for modal.

Errors: invalid_request (400), unauthenticated (401), forbidden (403), rate_limited (429), internal_error (500), unprocessable_source (422), quota_exceeded (429), engine_unavailable (503)

cURL

curl -sS -X POST https://<host>/v1/runs \
  -H "Authorization: Bearer $SCRIPTRIP_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"source":{"type":"youtube","url":"https://youtu.be/dQw4w9WgXcQ"},"name_speakers":true}'

GET `/v1/runs`

List runs. Cursor-paginated, newest first, scoped to your account. segments is absent from every element in every status — fetch one run, or fetch its transcript.

Scope: runs:read

Parameters

Name	In	Type	Notes
`limit`	query	`integer`	Default 25, in [1, 100]. Outside the range is 400 invalid_request, never clamped.
`cursor`	query	`string`	Opaque, from the previous page's next_cursor. Never construct one.
`status` (repeatable)	query	`RunStatus`	Repeatable; values union. A value outside 02 §4.2 is 400.
`source_type`	query	`SourceType`

Responses

200 — A page.

Field	Type	Required	Notes
`data`	`Run[]`	yes	segments is absent from every element, in every status.
`has_more`	`boolean`	yes	Authoritative. Loop on this, not on whether data is empty.
`next_cursor`	`string \| null`	yes	Opaque. null when has_more is false.

{
  "data": [
    {
      "id": "0195c8e4-8d02-7c19-b3e7-5a1f9d20c68b",
      "source_type": "youtube",
      "source_url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
      "source_upload_id": null,
      "title": "The Long Way South — Part 4",
      "author_name": "Sailing Somewhere",
      "author_url": "https://www.youtube.com/@sailingsomewhere",
      "description": null,
      "published_on": "2026-03-04",
      "duration_seconds": 2711.5,
      "thumbnail_url": "https://i.ytimg.com/vi/dQw4w9WgXcQ/mqdefault.jpg",
      "status": "done",
      "lane": "modal",
      "engine": "whisperx large-v2",
      "current_step": null,
      "step_log": [
        {
          "step": "fetch",
          "started_at": "2026-03-11T18:04:22Z",
          "ended_at": "2026-03-11T18:05:09Z",
          "ok": true,
          "detail": "45.2 MB in 47 s"
        },
        {
          "step": "normalize",
          "started_at": "2026-03-11T18:05:09Z",
          "ended_at": "2026-03-11T18:05:18Z",
          "ok": true,
          "detail": "2711.5 s · 16 kHz mono"
        },
        {
          "step": "transcribe",
          "started_at": "2026-03-11T18:05:18Z",
          "ended_at": "2026-03-11T18:07:44Z",
          "ok": true,
          "detail": "412 segments · language en"
        },
        {
          "step": "align",
          "started_at": "2026-03-11T18:07:44Z",
          "ended_at": "2026-03-11T18:08:31Z",
          "ok": true,
          "detail": "word-level timestamps for 412 segments"
        },
        {
          "step": "diarize",
          "started_at": "2026-03-11T18:08:31Z",
          "ended_at": "2026-03-11T18:09:40Z",
          "ok": true,
          "detail": "2 speakers over 412 segments"
        },
        {
          "step": "name_speakers",
          "started_at": "2026-03-11T18:09:40Z",
          "ended_at": "2026-03-11T18:09:55Z",
          "ok": true,
          "detail": "named 2 of 2"
        },
        {
          "step": "finalize",
          "started_at": "2026-03-11T18:09:55Z",
          "ended_at": "2026-03-11T18:09:57Z",
          "ok": true,
          "detail": "412 segments · 6841 words"
        }
      ],
      "language": "en",
      "requested_language": null,
      "name_speakers": true,
      "segment_count": 412,
      "speaker_count": 2,
      "word_count": 6841,
      "speaker_labels": {
        "SPEAKER_00": {
          "name": "Matt",
          "role": "host"
        },
        "SPEAKER_01": {
          "name": "Amy",
          "role": "guest"
        }
      },
      "cached_from_run_id": null,
      "media_fingerprint": "dQw4w9WgXcQ",
      "error": null,
      "error_class": null,
      "retry_after": null,
      "idempotency_key": "4f0a9e21-59f2-4d64-8e18-7d9b0b1c66aa",
      "created_at": "2026-03-11T18:04:11Z",
      "updated_at": "2026-03-11T18:09:57Z",
      "completed_at": "2026-03-11T18:09:57Z",
      "transcript_url": "https://<host>/v1/runs/0195c8e4-8d02-7c19-b3e7-5a1f9d20c68b/transcript",
      "expected_steps": [
        "fetch",
        "normalize",
        "transcribe",
        "align",
        "diarize",
        "name_speakers",
        "finalize"
      ],
      "seconds_until_modal": null,
      "live_workers": null,
      "worker_label": null,
      "machine_quiet": false
    }
  ],
  "has_more": true,
  "next_cursor": "eyJjIjoiMjAyNi0wMy0xMVQxODowNDoxMVoiLCJpIjoiMDE5NWM4ZTQtOGQwMi03YzE5LWIzZTctNWExZjlkMjBjNjhiIn0"
}

Errors: invalid_request (400), unauthenticated (401), forbidden (403), rate_limited (429), internal_error (500)

cURL

curl -sS "https://<host>/v1/runs?status=done&limit=10" -H "Authorization: Bearer $SCRIPTRIP_KEY"

GET `/v1/runs/{id}`

One run. The polling endpoint. segments and speaker_labels are populated only when status is done. Poll no faster than every 2 seconds, back off to 10 seconds after a minute — or register a destination and do not poll at all.

Scope: runs:read

This read writes. Runs the stale sweep and the Modal fallback clock — age-guarded, idempotent, and only while somebody is actually waiting (02 §8.1).

Parameters

Name	In	Type	Notes
`id`	path	`uuid`	The run id.

Responses

200 — The run.

Field	Type	Required	Notes
`id`	`uuid`	yes
`source_type`	`SourceType`	yes
`source_url`	`uri \| null`		Always null for upload and recording.
`source_upload_id`	`uuid \| null`		Always null for youtube; null after the upload row is deleted.
`title`	`string \| null`		null until acquisition learns it. Never invented.
`author_name`	`string \| null`
`author_url`	`uri \| null`
`description`	`string \| null`
`published_on`	`date \| null`		A bare calendar date.
`duration_seconds`	`number \| null`		null until normalize establishes it.
`thumbnail_url`	`uri \| null`
`status`	`RunStatus`	yes
`lane`	`Lane`		null until a lane takes it. modal_pending is a guard value, not a lane.
`engine`	`string \| null`		A human string ("whisperx large-v2"), not an enumeration. Do not branch on it.
`current_step`	`Step \| null`
`step_log`	`StepEntry[]`	yes
`language`	`string \| null`		BCP-47-ish; null until ASR detects it.
`requested_language`	`string \| null`
`name_speakers`	`boolean`	yes	What was asked for, not what happened.
`segments`	`Segment[] \| null`		null until status is done — "not yet", never "there is none". Never present in GET /v1/runs or in a webhook body.
`segment_count`	`integer \| null`
`speaker_count`	`integer \| null`		0 is a real value: diarization produced nothing.
`word_count`	`integer \| null`
`speaker_labels`	`object (free) \| null`		Keyed by speaker id (SPEAKER_00, …). null until done, and on a done run where nothing was named.
`cached_from_run_id`	`uuid \| null`		Set only when lane is cached.
`media_fingerprint`	`string \| null`		The canonical video id, or the media sha256.
`error`	`string \| null`		A sentence for a person. Programs branch on error_class.
`error_class`	`ErrorClass \| null`
`retry_after`	`date-time \| null`		Set on error_class premiere: when to submit a NEW run.
`idempotency_key`	`string \| null`
`created_at`	`date-time`	yes
`updated_at`	`date-time`	yes
`completed_at`	`date-time \| null`		Non-null on every terminal status.
`transcript_url`	`uri \| null`		Derived. The absolute GET /v1/runs/{id}/transcript URL; null unless done.
`expected_steps`	`Step[] \| null`		Derived. null while lane is null or modal_pending — draw no checklist.
`seconds_until_modal`	`integer \| null`		Derived. null unless queued with no lane and the countdown is running.
`live_workers`	`object \| null`		Derived. null unless the countdown is running.
`worker_label`	`string \| null`		Derived. The machine's display label; null unless a fleet worker holds the run. claimed_by is never sent.
`machine_quiet`	`boolean`	yes	Derived, never null. True only for a fleet run whose worker has stopped heartbeating; always false for modal.

{
  "id": "0195c8e4-8d02-7c19-b3e7-5a1f9d20c68b",
  "source_type": "youtube",
  "source_url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
  "source_upload_id": null,
  "title": "The Long Way South — Part 4",
  "author_name": "Sailing Somewhere",
  "author_url": "https://www.youtube.com/@sailingsomewhere",
  "description": null,
  "published_on": "2026-03-04",
  "duration_seconds": 2711.5,
  "thumbnail_url": "https://i.ytimg.com/vi/dQw4w9WgXcQ/mqdefault.jpg",
  "status": "done",
  "lane": "modal",
  "engine": "whisperx large-v2",
  "current_step": null,
  "step_log": [
    {
      "step": "fetch",
      "started_at": "2026-03-11T18:04:22Z",
      "ended_at": "2026-03-11T18:05:09Z",
      "ok": true,
      "detail": "45.2 MB in 47 s"
    },
    {
      "step": "normalize",
      "started_at": "2026-03-11T18:05:09Z",
      "ended_at": "2026-03-11T18:05:18Z",
      "ok": true,
      "detail": "2711.5 s · 16 kHz mono"
    },
    {
      "step": "transcribe",
      "started_at": "2026-03-11T18:05:18Z",
      "ended_at": "2026-03-11T18:07:44Z",
      "ok": true,
      "detail": "412 segments · language en"
    },
    {
      "step": "align",
      "started_at": "2026-03-11T18:07:44Z",
      "ended_at": "2026-03-11T18:08:31Z",
      "ok": true,
      "detail": "word-level timestamps for 412 segments"
    },
    {
      "step": "diarize",
      "started_at": "2026-03-11T18:08:31Z",
      "ended_at": "2026-03-11T18:09:40Z",
      "ok": true,
      "detail": "2 speakers over 412 segments"
    },
    {
      "step": "name_speakers",
      "started_at": "2026-03-11T18:09:40Z",
      "ended_at": "2026-03-11T18:09:55Z",
      "ok": true,
      "detail": "named 2 of 2"
    },
    {
      "step": "finalize",
      "started_at": "2026-03-11T18:09:55Z",
      "ended_at": "2026-03-11T18:09:57Z",
      "ok": true,
      "detail": "412 segments · 6841 words"
    }
  ],
  "language": "en",
  "requested_language": null,
  "name_speakers": true,
  "segments": [
    {
      "start": 0.48,
      "end": 4.02,
      "text": "Right, so this is day nine.",
      "speaker": "SPEAKER_00"
    },
    {
      "start": 4.02,
      "end": 7.61,
      "text": "Day nine and we still haven't seen land.",
      "speaker": "SPEAKER_00"
    },
    {
      "start": 8.1,
      "end": 11.44,
      "text": "I keep telling him that's the point.",
      "speaker": "SPEAKER_01"
    }
  ],
  "segment_count": 412,
  "speaker_count": 2,
  "word_count": 6841,
  "speaker_labels": {
    "SPEAKER_00": {
      "name": "Matt",
      "role": "host"
    },
    "SPEAKER_01": {
      "name": "Amy",
      "role": "guest"
    }
  },
  "cached_from_run_id": null,
  "media_fingerprint": "dQw4w9WgXcQ",
  "error": null,
  "error_class": null,
  "retry_after": null,
  "idempotency_key": "4f0a9e21-59f2-4d64-8e18-7d9b0b1c66aa",
  "created_at": "2026-03-11T18:04:11Z",
  "updated_at": "2026-03-11T18:09:57Z",
  "completed_at": "2026-03-11T18:09:57Z",
  "transcript_url": "https://<host>/v1/runs/0195c8e4-8d02-7c19-b3e7-5a1f9d20c68b/transcript",
  "expected_steps": [
    "fetch",
    "normalize",
    "transcribe",
    "align",
    "diarize",
    "name_speakers",
    "finalize"
  ],
  "seconds_until_modal": null,
  "live_workers": null,
  "worker_label": null,
  "machine_quiet": false
}

Errors: unauthenticated (401), forbidden (403), rate_limited (429), internal_error (500), not_found (404)

cURL

curl -sS "https://<host>/v1/runs/$RUN_ID" -H "Authorization: Bearer $SCRIPTRIP_KEY"

DELETE `/v1/runs/{id}`

Delete a run and its media. Deletes the row and purges its media immediately. A run in flight is cancelled first, in the same transaction, so run.canceled fires before the row disappears. Always 200 with a receipt, never 204; a second delete is 404.

Scope: runs:write

Parameters

Name	In	Type	Notes
`id`	path	`uuid`	The run id.

Responses

200 — A receipt.

Field	Type	Required
`id`	`uuid`	yes
`deleted`	`boolean`	yes
`media_objects_purged`	`integer`	yes
`message`	`string`	yes

{
  "id": "0195c8e4-8d02-7c19-b3e7-5a1f9d20c68b",
  "deleted": true,
  "media_objects_purged": 1,
  "message": "The run and 1 media object were deleted."
}

Errors: unauthenticated (401), forbidden (403), rate_limited (429), internal_error (500), not_found (404)

cURL

curl -sS -X DELETE "https://<host>/v1/runs/$RUN_ID" -H "Authorization: Bearer $SCRIPTRIP_KEY"

POST `/v1/runs/{id}/cancel`

Stop a run in flight. Empty body. Cancellation is cooperative at the worker's next step boundary; a step in flight is not interrupted. run.canceled is enqueued in the same transaction. A run already terminal is 409 conflict with its actual status in detail.

Scope: runs:write

Parameters

Name	In	Type	Notes
`id`	path	`uuid`	The run id.

Responses

200 — The run, now terminal, plus a sentence naming what to expect.

Field	Type	Required	Notes
`id`	`uuid`	yes
`source_type`	`SourceType`
`source_url`	`uri \| null`		Always null for upload and recording.
`source_upload_id`	`uuid \| null`		Always null for youtube; null after the upload row is deleted.
`title`	`string \| null`		null until acquisition learns it. Never invented.
`author_name`	`string \| null`
`author_url`	`uri \| null`
`description`	`string \| null`
`published_on`	`date \| null`		A bare calendar date.
`duration_seconds`	`number \| null`		null until normalize establishes it.
`thumbnail_url`	`uri \| null`
`status`	`RunStatus`	yes
`lane`	`Lane`		null until a lane takes it. modal_pending is a guard value, not a lane.
`engine`	`string \| null`		A human string ("whisperx large-v2"), not an enumeration. Do not branch on it.
`current_step`	`Step \| null`
`step_log`	`StepEntry[]`
`language`	`string \| null`		BCP-47-ish; null until ASR detects it.
`requested_language`	`string \| null`
`name_speakers`	`boolean`		What was asked for, not what happened.
`segments`	`Segment[] \| null`		null until status is done — "not yet", never "there is none". Never present in GET /v1/runs or in a webhook body.
`segment_count`	`integer \| null`
`speaker_count`	`integer \| null`		0 is a real value: diarization produced nothing.
`word_count`	`integer \| null`
`speaker_labels`	`object (free) \| null`		Keyed by speaker id (SPEAKER_00, …). null until done, and on a done run where nothing was named.
`cached_from_run_id`	`uuid \| null`		Set only when lane is cached.
`media_fingerprint`	`string \| null`		The canonical video id, or the media sha256.
`error`	`string \| null`		A sentence for a person. Programs branch on error_class.
`error_class`	`ErrorClass \| null`	yes
`retry_after`	`date-time \| null`		Set on error_class premiere: when to submit a NEW run.
`idempotency_key`	`string \| null`
`created_at`	`date-time`
`updated_at`	`date-time`
`completed_at`	`date-time \| null`		Non-null on every terminal status.
`transcript_url`	`uri \| null`		Derived. The absolute GET /v1/runs/{id}/transcript URL; null unless done.
`expected_steps`	`Step[] \| null`		Derived. null while lane is null or modal_pending — draw no checklist.
`seconds_until_modal`	`integer \| null`		Derived. null unless queued with no lane and the countdown is running.
`live_workers`	`object \| null`		Derived. null unless the countdown is running.
`worker_label`	`string \| null`		Derived. The machine's display label; null unless a fleet worker holds the run. claimed_by is never sent.
`machine_quiet`	`boolean`		Derived, never null. True only for a fleet run whose worker has stopped heartbeating; always false for modal.
`message`	`string`	yes

{
  "id": "0195c8e4-8d02-7c19-b3e7-5a1f9d20c68b",
  "source_type": "youtube",
  "source_url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
  "source_upload_id": null,
  "title": null,
  "author_name": null,
  "author_url": null,
  "description": null,
  "published_on": null,
  "duration_seconds": null,
  "thumbnail_url": null,
  "status": "canceled",
  "lane": "modal",
  "engine": "whisperx large-v2",
  "current_step": null,
  "step_log": [],
  "language": null,
  "requested_language": null,
  "name_speakers": true,
  "segments": null,
  "segment_count": null,
  "speaker_count": null,
  "word_count": null,
  "speaker_labels": null,
  "cached_from_run_id": null,
  "media_fingerprint": "dQw4w9WgXcQ",
  "error": "Stopped by a person.",
  "error_class": "canceled",
  "retry_after": null,
  "idempotency_key": "4f0a9e21-59f2-4d64-8e18-7d9b0b1c66aa",
  "created_at": "2026-03-11T18:04:11Z",
  "updated_at": "2026-03-11T18:06:02Z",
  "completed_at": "2026-03-11T18:06:02Z",
  "transcript_url": null,
  "expected_steps": [
    "fetch",
    "normalize",
    "transcribe",
    "align",
    "diarize",
    "name_speakers",
    "finalize"
  ],
  "seconds_until_modal": null,
  "live_workers": null,
  "worker_label": null,
  "machine_quiet": false,
  "message": "Stopped. The GPU finishes what it is in the middle of and shuts down; you are not charged for the rest."
}

Errors: unauthenticated (401), forbidden (403), rate_limited (429), internal_error (500), not_found (404), conflict (409)

cURL

curl -sS -X POST "https://<host>/v1/runs/$RUN_ID/cancel" -H "Authorization: Bearer $SCRIPTRIP_KEY"

GET `/v1/runs/{id}/transcript`

The transcript, in one format, as text. Six renderings of one segments array. A run that is not done is 409 conflict with its status in detail. ?download=1 adds a Content-Disposition attachment header.

Scope: runs:read

Parameters

Name	In	Type	Notes
`id`	path	`uuid`	The run id.
`format`	query	`OutputFormat`	Default speakers.
`download`	query	`integer`	1 to receive it as an attachment named after the title.

Responses

200 — text/plain for prose, speakers and timestamped; application/x-subrip for srt; text/vtt for vtt; application/json for json.

Matt: Right, so this is day nine. Day nine and we still haven't seen land.

Amy: I keep telling him that's the point.

Errors: invalid_request (400), unauthenticated (401), forbidden (403), rate_limited (429), internal_error (500), not_found (404), conflict (409)

cURL

curl -sS "https://<host>/v1/runs/$RUN_ID/transcript?format=srt" \
  -H "Authorization: Bearer $SCRIPTRIP_KEY" -o transcript.srt

POST `/v1/runs/{id}/deliver`

Send this run to a destination now. Re-delivery for a program: enqueues a delivery on the same retry ladder as the one the terminal transition enqueued. Requires runs:read AND destinations:write together (02 §8). A run that is not terminal, or a destination that is disabled, is 409 conflict.

Scope: runs:read and destinations:write

Parameters

Name	In	Type	Notes
`id`	path	`uuid`	The run id.

Request body

Field	Type	Required	Notes
`destination_id`	`uuid`	yes	Must belong to your account; one that does not is 404.
`event`	`WebhookEvent`		Defaults to the event the run's terminal status implies.

{
  "destination_id": "6d2b8a10-1f47-4c8e-a2f0-cb9e4d3a7711"
}

Responses

202 — Queued.

Field	Type	Required
`delivery_id`	`uuid`	yes
`destination_id`	`uuid`	yes
`run_id`	`uuid`	yes
`event`	`WebhookEvent`	yes
`status`	`DeliveryStatus`	yes
`message`	`string`	yes

{
  "delivery_id": "8c41d0aa-63e2-4a52-9f77-2b1c0e8d4a90",
  "destination_id": "6d2b8a10-1f47-4c8e-a2f0-cb9e4d3a7711",
  "run_id": "0195c8e4-8d02-7c19-b3e7-5a1f9d20c68b",
  "event": "run.completed",
  "status": "pending",
  "created": true,
  "message": "Queued for delivery. The sender runs every minute; the first attempt goes out on its next pass."
}

Errors: invalid_request (400), unauthenticated (401), forbidden (403), rate_limited (429), internal_error (500), not_found (404), conflict (409)

cURL

curl -sS -X POST "https://<host>/v1/runs/$RUN_ID/deliver" \
  -H "Authorization: Bearer $SCRIPTRIP_KEY" \
  -H "Content-Type: application/json" \
  -d '{"destination_id":"$DEST_ID"}'

Runs

POST /v1/runs

Parameters

Request body

Responses

cURL

GET /v1/runs

Parameters

Responses

cURL

GET /v1/runs/{id}

Parameters

Responses

cURL

DELETE /v1/runs/{id}

Parameters

Responses

cURL

POST /v1/runs/{id}/cancel

Parameters

Responses

cURL

GET /v1/runs/{id}/transcript

Parameters

Responses

cURL

POST /v1/runs/{id}/deliver

Parameters

Request body

Responses

cURL

POST `/v1/runs`

GET `/v1/runs`

GET `/v1/runs/{id}`

DELETE `/v1/runs/{id}`

POST `/v1/runs/{id}/cancel`

GET `/v1/runs/{id}/transcript`

POST `/v1/runs/{id}/deliver`