Retrieve a Generation
Retrieve the status and result of a generation in the current organization. Requires Bearer authentication.
GET /v2/generations/{id}
Path parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
id | string | Yes | ID returned when creating the generation. A positive int64 represented as a decimal string, with no leading zeros. |
Example request
Set SAND_GENERATION_ID to the saved generation ID. Use the same ID if polling is interrupted.
export SAND_GENERATION_ID='123456789'
curl "https://api.sand.ai/v2/generations/$SAND_GENERATION_ID" \
-H "Authorization: Bearer $SAND_API_KEY"
Response
A successful retrieval returns HTTP 200 OK and Cache-Control: no-store. Check status for the generation outcome.
{
"id": "123456789",
"status": "succeeded",
"output": {
"videoUrl": "https://files.example.com/video.mp4?signature=example",
"urlExpiresAt": "2026-11-02T03:00:00.000Z"
},
"error": null,
"createdAt": "2026-11-02T01:55:00.000Z"
}
All five top-level fields are always present. Timestamps use RFC 3339 in UTC with millisecond precision.
| Field | Type | Description |
|---|---|---|
id | string | Generation ID. |
status | string | Generation status, listed below. |
output | object | null | Result object on success; otherwise null. |
output.videoUrl | string | null | Video download URL. |
output.urlExpiresAt | string | null | Download URL expiration time. |
error | object | null | Failure information when failed; otherwise null. |
error.code | string | Failure code. See Generation Failures. |
error.message | string | Failure description. |
createdAt | string | Generation creation time. |
Statuses
| Status | Meaning | Action |
|---|---|---|
queued | Waiting to run. | Continue polling. |
processing | Preparing, generating, or undergoing moderation. | Continue polling. |
succeeded | Generation completed. | Check the download URL and retrieve the video. |
failed | Generation or moderation failed. | Stop polling and check error. |
canceled | Generation was canceled. | Stop polling. |
Poll one generation every 10 seconds. For multiple generations, stagger requests and increase the interval to stay within the organization’s read quota. See Rate limits, polling and retries.
Download the video
Check that output and output.videoUrl are not null before downloading. The download does not require an API key. URLs are valid for 60 minutes; use urlExpiresAt for the exact expiration. Retrieve the generation again to obtain a fresh URL.
If the output of a successful task is unavailable, its URL fields may be null. Later moderation decisions can affect access; use the latest retrieval response.
If the generation is missing, deleted, or belongs to another organization, the endpoint returns 404 generation_not_found. See Errors for other request failures.
The owning organization can retrieve the task by ID during its retention period even after model access is revoked.