Prompt runs

Summary

Prompt runs are the execution boundary for extraction. The API exposes run creation, status inspection, cancellation, segment results, media-wide synthesis, failed-segment manifests, and debug-oriented LLM call access.

Prompt run endpoints

Method	Path	Purpose
`POST`	`/api/v2/prompt-runs/execute`	Start a prompt run
`GET`	`/api/v2/prompt-runs`	List runs
`GET`	`/api/v2/prompt-runs/{run_id}`	Retrieve run status
`POST`	`/api/v2/prompt-runs/{run_id}/cancel`	Request cancellation
`GET`	`/api/v2/prompt-runs/{run_id}/results`	Paginate segment results
`GET`	`/api/v2/prompt-runs/{run_id}/videos/{video_id}/video-result`	Retrieve media-wide synthesis
`GET`	`/api/v2/prompt-runs/{run_id}/failed-segments`	Retrieve failed-segment manifest
`POST`	`/api/v2/prompt-runs/{run_id}/videos/{video_id}/segments/{segment_id}/retry`	Retry one failed segment
`GET`	`/api/v2/prompt-runs/{run_id}/videos/{video_id}/segments/{segment_id}/retries/{retry_id}`	Inspect retry status
`GET`	`/api/v2/prompt-runs/{run_id}/llm-calls`	Inspect LLM calls for debugging

Execute request

The public execute request uses:

Field	Type	Notes
`prompt_id`	`string`	Prompt to execute
`target`	`object`	One of `index`, `videos`, or `playground`
`video_segmentation_type`	`smart`, `fixed`, or `content_aware`	Video segmentation mode
`audio_segmentation_type`	`fixed` or `content_aware`	Audio segmentation mode
`video_segment_duration`	`integer`	Required for `fixed` video segmentation
`audio_segment_duration`	`integer`	Required for `fixed` audio segmentation
`processing_model`	`string`	Optional extraction model
`enable_transcription`	`boolean`	Enable speech-to-text
`enable_image_embedding`	`boolean`	Enable image-search embeddings

Example: execute against an index

curl -X POST /api/v2/prompt-runs/execute \
  -H "X-API-Key: sk_live_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: run-archive-2026-04-20" \
  -d '{
    "prompt_id": "prompt_scene_extract",
    "target": {
      "type": "index",
      "index_id": "idx_archive"
    },
    "video_segmentation_type": "smart",
    "audio_segmentation_type": "content_aware",
    "processing_model": "gemini-2.5-flash",
    "enable_transcription": true,
    "enable_image_embedding": true
  }'

Result retrieval

GET /api/v2/prompt-runs/{run_id}/results requires video_id as a query parameter so the response can paginate one media item's segment-level records at a time.

curl "/api/v2/prompt-runs/run_123/results?video_id=vid_456&limit=50" \
  -H "X-API-Key: sk_live_..."

Failure handling

Use the failed-segment manifest before retrying:

Retrieve /failed-segments.
Inspect the failed operation counts and retryability.
Retry only the affected segment.
Poll the retry status endpoint until terminal.

Cancellation

Cancellation is cooperative. The stop request is stored on the run, and work already in progress may still finish before the run reaches a terminal state.

Estimate endpoint

The platform also exposes POST /api/v2/prompt-runs/estimate with the same request shape as execution. It is useful for dry-run validation before execution, but billing interpretation is intentionally out of scope for this documentation set.

SDK equivalents

client.prompt_runs.execute
client.prompt_runs.retrieve
client.prompt_runs.list_results
client.prompt_runs.get_video_result
client.prompt_runs.get_failed_segments
client.prompt_runs.retry_segment
client.prompt_runs.get_segment_retry_status

Tip

Prompt-run scope also affects search. If an index has several runs, pass explicit run_ids to search APIs when you need deterministic retrieval against a known execution boundary.

Prompts

Go to previous page

Search and SQL search

Go to next page

Prompt runs

Search documentation

Related documentation