---
title: "Fetch a video"
method: GET
path: "/v1/videos/{id}"
tags: ["videos"]
---

# Fetch a video

`GET /v1/videos/{id}`

## Request

- Base URL: `https://api.primateintelligence.ai`
- URL: `https://api.primateintelligence.ai/v1/videos/{id}`
- Auth: HTTP bearer

## Path parameters

- `id` string, required

## Response `200`

The video.

- Video: A source video (§13.1).
  - `id` string, required: Video resource id (prefixed ULID). Immutable.
  - `object` 'video', required
  - `livemode` boolean, required: true when the request used a live key; false for test keys and sandbox. Stripe-style.
  - `status` 'awaiting_upload' | 'processing' | 'ready' | 'failed', required: Video lifecycle state (§14.1).
  - `filename` string, nullable, required
  - `size_bytes` integer, nullable, required
  - `duration_s` number, nullable, required
  - `width` integer, nullable, required
  - `height` integer, nullable, required
  - `fps` number, nullable, required
  - `content_type` 'video/mp4' | 'video/quicktime', required
  - `source` 'upload' | 'url', required
  - `upload` VideoUpload, nullable, required: Presigned upload instructions. Present only while awaiting_upload. URL TTL 1h.
    - `method` 'PUT', required
    - `url` string, uri, required
    - `headers` object, required
    - `expires_at` string, date-time, required
  - `media` VideoMedia, nullable: Signed 1h playback URL for the source video (sign-on-read — re-fetch for a fresh URL). Null while not ready or when no stored source object exists.
    - `url` string, uri, required
    - `expires_at` string, date-time, required
  - `error` ErrorObject, nullable, required
    - `code` string, required
    - `message` string, required
  - `metadata` object: Free-form key/value metadata. ≤16 keys, key ≤40 chars [a-zA-Z0-9_.-], value ≤500 chars.
  - `expires_at` string, date-time, nullable, required
  - `created_at` string, date-time, required

## Other responses

- `400`: validation_failed / url_forbidden / prompt errors (§15)
- `401`: invalid_api_key / key_revoked / key_expired
- `404`: resource_not_found (account-scoped; no existence oracle)
- `409`: resource_conflict / idempotency_key_reused / idempotency_unavailable
- `429`: rate_limit_exceeded / concurrency_limit_exceeded / quota_exceeded (always with Retry-After)

---

[API](https://skmtc.dev/primateintelligence/apis/primate-vision-api.md) · [All operations](https://skmtc.dev/primateintelligence/apis/primate-vision-api/llms.txt) · [OpenAPI document](https://skmtc.dev/primateintelligence/apis/primate-vision-api/revisions/aa51b01dc8ad?raw)