> ## Documentation Index > Fetch the complete documentation index at: https://docs.hopscotchlabs.ai/llms.txt > Use this file to discover all available pages before exploring further. # Retrieve a video job > Read back the provider's current job object for a video job, for the account that created it. A terminal status seen here settles the job's money once; the read itself writes no usage row and is charged nothing. Charging reads the seconds the provider reports for the finished render, never the requested duration; where the provider reports none, the full hold is charged. External delivery URLs are omitted from the answer; download finished bytes through `GET /v1/videos/{id}/content`. ## OpenAPI ````yaml /api-reference/openapi.public.json get /v1/videos/{id} openapi: 3.0.3 info: title: Hopscotch version: v1 description: >- An OpenAI-compatible inference API. Point an OpenAI client at https://api.hopscotchlabs.ai, give it a Hopscotch API key, and call models across providers on one prepaid balance. Every response, errors included, matches the shape an unmodified OpenAI SDK expects. servers: - url: https://api.hopscotchlabs.ai description: Production security: - customerApiKey: [] tags: - name: Chat description: Chat completions, streamed or not. - name: Models description: What you can call. - name: Completions description: Text completions, streamed or not. - name: Messages description: The Anthropic Messages API, streamed or not. - name: Usage description: What one request recorded and what it cost. - name: Videos description: 'Video jobs: create, poll, download, delete.' paths: /v1/videos/{id}: get: tags: - Videos summary: Retrieve a video job description: >- Read back the provider's current job object for a video job, for the account that created it. A terminal status seen here settles the job's money once; the read itself writes no usage row and is charged nothing. Charging reads the seconds the provider reports for the finished render, never the requested duration; where the provider reports none, the full hold is charged. External delivery URLs are omitted from the answer; download finished bytes through `GET /v1/videos/{id}/content`. operationId: retrieveVideo parameters: - name: id in: path required: true description: The video job id the create answered. schema: type: string example: video_123 responses: '200': description: >- The provider's video job object with external URLs omitted and its `model` field rewritten to the public id the create returned (`provider/model`). headers: x-hopscotch-request-id: $ref: '#/components/headers/RequestId' content: application/json: schema: $ref: '#/components/schemas/VideoJob' example: id: video_123 object: video model: openai/sora-2 status: in_progress progress: 40 created_at: 1788998400 size: 1280x720 seconds: '8' '401': description: >- No key, a scheme other than Bearer, a key of the wrong shape, or a key we reject. An unknown key and a revoked key are answered with one identical message on purpose. A key past its own expiry date is refused here too, with code `key_expired` and a message naming the date. It is checked before the per-minute rate limiter, so an expired key never consumes that allowance. Expired keys are not renewed: create a new one. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: message: Incorrect API key provided. type: authentication_error param: null code: invalid_api_key request_id: REQUEST_ID headers: x-hopscotch-request-id: $ref: '#/components/headers/RequestId' '404': description: >- No video with this id is visible to this key: a video another account made and an id that never existed answer identically, and the provider is not called. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: message: >- No video "video_123" is visible to this key. A video made by another account and an id that never existed answer identically. type: invalid_request_error param: video_id code: video_not_found request_id: REQUEST_ID headers: x-hopscotch-request-id: $ref: '#/components/headers/RequestId' '429': description: >- A limit refused the request. `rate_limit_exceeded` is this key's own request rate and carries `Retry-After`. `spend_rate_exceeded` is the account spend rate cap, which counts the credit held for requests rather than the credit they settle at, and carries `Retry-After`. `upstream_rate_limited` is the model's provider rate-limiting the call: nothing about the request is wrong, nothing is charged, and it carries `Retry-After`. headers: Retry-After: schema: type: integer minimum: 1 description: >- Seconds to wait. Present on `rate_limit_exceeded`, `spend_rate_exceeded` and `upstream_rate_limited`. example: 17 x-hopscotch-request-id: $ref: '#/components/headers/RequestId' content: application/json: schema: $ref: '#/components/schemas/Error' examples: rate_limit_exceeded: summary: This key's request rate value: error: message: >- Rate limit reached for this key. Try again in 12 seconds. Request id REQUEST_ID. type: rate_limit_error param: null code: rate_limit_exceeded request_id: REQUEST_ID spend_rate_exceeded: summary: The account spend rate cap value: error: message: >- This account has already reserved 5000 minor units in the last 60 seconds, which is at its ceiling of 5000. Requests are admitted again within 60 seconds of the earliest reservation counted, with nothing to do in the meantime. type: rate_limit_error param: null code: spend_rate_exceeded request_id: REQUEST_ID upstream_rate_limited: summary: The model's provider rate-limited the call value: error: message: >- The provider serving this model is rate-limiting requests right now. Nothing was charged. Retry after the number of seconds in the Retry-After header. Quote the request id if you contact support. type: rate_limit_error param: null code: upstream_rate_limited request_id: REQUEST_ID '502': description: >- The provider holding the job could not be reached (`provider_unavailable`), or the answer it gave could not be read (`invalid_provider_response`). Nothing was charged. content: application/json: schema: $ref: '#/components/schemas/Error' examples: provider_unavailable: summary: The provider could not be reached value: error: message: >- The provider that holds this video could not be reached. Nothing was charged; try again shortly. type: api_error param: null code: provider_unavailable request_id: REQUEST_ID invalid_provider_response: summary: The provider's answer could not be read value: error: message: The video response could not be read. type: api_error param: null code: invalid_provider_response request_id: REQUEST_ID headers: x-hopscotch-request-id: $ref: '#/components/headers/RequestId' security: - customerApiKey: [] servers: - url: https://api.hopscotchlabs.ai description: Production components: headers: RequestId: description: >- Our id for this request. Quote it when you contact support. Present on every response, errors included. schema: type: string schemas: VideoJob: type: object description: >- One video job, as the provider reports it, with external URLs omitted and `model` rewritten to the public id the create returned. Providers report different extra fields; only the fields below are promised. required: - id - object - model - status additionalProperties: true properties: id: type: string description: The job id the create answered. Pass it to the follow-up paths. example: video_123 object: type: string enum: - video model: type: string description: >- The public `provider/model` id the create returned, so a poll names the model exactly as the create did. example: openai/sora-2 status: type: string description: >- Where the job stands. A provider that answers `succeeded` means completed. enum: - queued - in_progress - completed - failed - cancelled - succeeded progress: type: integer description: How far along the provider says the job is, 0 to 100. created_at: type: integer description: When the job was created, in Unix seconds. nullable: true size: type: string description: The requested size, in OpenAI `WIDTHxHEIGHT` spelling. example: 1280x720 seconds: type: string description: >- The seconds of video, as a decimal string. A completed job reports what it rendered; settlement never charges above what the hold covered. example: '8' error: type: object description: >- Present when the job failed: the provider's reason, with a stable `code` and a prose `message`. properties: code: type: string example: video_generation_failed message: type: string Error: type: object description: The error envelope. One top-level `error` key, always, at every status. required: - error additionalProperties: false properties: error: type: object required: - message - type - param - code additionalProperties: false properties: message: type: string description: Prose for a person. It may be reworded, so do not branch on it. type: type: string description: The category an SDK branches on. A closed set. enum: - invalid_request_error - authentication_error - permission_error - not_found_error - rate_limit_error - api_error - insufficient_quota - server_error param: type: string nullable: true description: >- The request field at fault, or null. Present and null rather than absent. code: type: string nullable: true description: The stable machine-readable reason. Branch on this. request_id: type: string description: >- Our id for this request, the same value as the x-hopscotch-request-id header. Quote it when you contact support. securitySchemes: customerApiKey: type: http scheme: bearer description: >- A workspace API key in an `Authorization: Bearer` header. A missing header, a scheme other than Bearer, a key of the wrong shape, and a key we reject are all 401. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.