Skip to content
Documentation navigation
On this page

Retrieve a Generation

Retrieve the status and result of a generation in the current organization. Requires Bearer authentication.

http
GET /v2/generations/{id}

Path parameters

ParameterTypeRequiredDescription
idstringYesID 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.

bash
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.

json
{
  "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.

FieldTypeDescription
idstringGeneration ID.
statusstringGeneration status, listed below.
outputobject | nullResult object on success; otherwise null.
output.videoUrlstring | nullVideo download URL.
output.urlExpiresAtstring | nullDownload URL expiration time.
errorobject | nullFailure information when failed; otherwise null.
error.codestringFailure code. See Generation Failures.
error.messagestringFailure description.
createdAtstringGeneration creation time.

Statuses

StatusMeaningAction
queuedWaiting to run.Continue polling.
processingPreparing, generating, or undergoing moderation.Continue polling.
succeededGeneration completed.Check the download URL and retrieve the video.
failedGeneration or moderation failed.Stop polling and check error.
canceledGeneration 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.