> ## Documentation Index
> Fetch the complete documentation index at: https://apidoc.cometapi.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Retrieve a HappyHorse video
> Retrieve a HappyHorse video task by task ID, including status, progress, timestamps, and the completed video URL.
Use this endpoint after you create a HappyHorse video task. It returns the task state and includes `video_url` after the task is completed.
## Check these fields
* `status` tells you whether the task is `queued`, `in_progress`, `completed`, `failed`, or `error`.
* `progress` is a coarse completion percentage.
* `video_url` appears on completed responses.
* `error` appears when a task fails.
## Polling flow
Start with [Create a HappyHorse video](./create) and store the returned `id`.
Send the task ID to this endpoint until `status` reaches `completed`, `failed`, or `error`.
When `status` is `completed`, call [Retrieve HappyHorse video content](./retrieve-content).
## OpenAPI
````yaml api/openapi/video/happyhorse/get-retrieve.openapi.json GET /v1/videos/{task_id}
openapi: 3.1.0
info:
title: HappyHorse Video Retrieve API
version: 1.0.0
description: >-
Retrieve a HappyHorse video task by task ID. Poll this endpoint until status
is completed, failed, or error.
servers:
- url: https://api.cometapi.com
security:
- bearerAuth: []
paths:
/v1/videos/{task_id}:
get:
summary: Retrieve a HappyHorse video task
description: >-
Read the state of a HappyHorse video task that was created through POST
/v1/videos.
operationId: happyhorse_retrieve_video
parameters:
- name: task_id
in: path
required: true
description: Task ID returned by POST /v1/videos.
schema:
type: string
example: task_example
responses:
'200':
description: Current HappyHorse video task state.
content:
application/json:
schema:
$ref: '#/components/schemas/HappyHorseVideoTask'
examples:
queued:
summary: Task queued
value:
id: task_example
model: happyhorse-1.0
object: video
status: queued
progress: 0
created_at: 1779938152
completed:
summary: Task completed
value:
id: task_example
model: happyhorse-1.0
object: video
status: completed
progress: 100
video_url:
created_at: 1779938152
completed_at: 1779938219
'400':
description: The task ID does not match a task for the authenticated user.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
error:
message: task_not_exist
type: invalid_request_error
'401':
description: The API key is missing or invalid.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
security:
- bearerAuth: []
x-codeSamples:
- lang: Shell
label: Retrieve task status
source: |-
curl https://api.cometapi.com/v1/videos/ \
-H "Authorization: Bearer $COMETAPI_KEY"
- lang: Python
label: Retrieve task status
source: |
import os
import time
import requests
TASK_ID = ""
headers = {"Authorization": "Bearer " + os.environ["COMETAPI_KEY"]}
terminal_statuses = {"completed", "failed", "error"}
while True:
response = requests.get(
f"https://api.cometapi.com/v1/videos/{TASK_ID}",
headers=headers,
timeout=60,
)
response.raise_for_status()
task = response.json()
print(task["status"], task.get("progress"))
if task["status"] in terminal_statuses:
print(task.get("video_url"))
break
time.sleep(10)
- lang: JavaScript
label: Retrieve task status
source: |
const TASK_ID = "";
const terminalStatuses = new Set(["completed", "failed", "error"]);
while (true) {
const response = await fetch(
`https://api.cometapi.com/v1/videos/${TASK_ID}`,
{ headers: { Authorization: `Bearer ${process.env.COMETAPI_KEY}` } },
);
const task = await response.json();
console.log(task.status, task.progress);
if (terminalStatuses.has(task.status)) {
console.log(task.video_url);
break;
}
await new Promise((resolve) => setTimeout(resolve, 10_000));
}
components:
schemas:
HappyHorseVideoTask:
type: object
required:
- id
- object
- model
- status
- progress
- created_at
properties:
id:
type: string
description: Task ID. Use this value as task_id in retrieve and content requests.
example: task_example
task_id:
type: string
description: Compatibility alias for id. The value matches id when present.
example: task_example
object:
type: string
description: Object type. HappyHorse video tasks return video.
example: video
model:
type: string
description: Model ID used for the task.
example: happyhorse-1.0
status:
type: string
description: >-
Task lifecycle status. Poll until the value is completed, failed, or
error.
enum:
- queued
- in_progress
- completed
- failed
- error
example: queued
progress:
type: integer
minimum: 0
maximum: 100
description: Task progress as a coarse percentage.
example: 0
created_at:
type: integer
description: Task creation time as a Unix timestamp in seconds.
example: 1779938152
completed_at:
type: integer
description: >-
Task completion time as a Unix timestamp in seconds. This field
appears on completed tasks.
example: 1779938219
video_url:
type: string
description: Temporary video delivery URL. This field appears on completed tasks.
example:
error:
type: object
description: Failure details. This field appears when the task fails.
additionalProperties: true
additionalProperties: true
ErrorResponse:
description: >-
Error body. Validation errors can use a top-level code and message,
while authentication errors can use an error object.
oneOf:
- type: object
required:
- message
properties:
code:
type:
- string
- 'null'
description: Short error code.
message:
type: string
description: Human-readable error message.
additionalProperties: true
- type: object
required:
- error
properties:
error:
type: object
required:
- message
properties:
message:
type: string
description: Human-readable error message.
type:
type: string
description: Error category.
code:
type:
- string
- 'null'
description: Short error code.
additionalProperties: true
additionalProperties: true
securitySchemes:
bearerAuth:
type: http
scheme: bearer
description: Bearer authentication. Use your CometAPI API key.
````