Get task
GET /v1/tasks/{id}: read a task, its status, output URLs and error. Reference for the task object and its statuses.
HTTP
GET https://genkiln.com/v1/tasks/{id}Returns one of your tasks. Tasks created by other accounts return 404 not_found.
curl https://genkiln.com/v1/tasks/task_01JC8ZQ0E6H2P4N7K9T3W5Y8VA \
-H "Authorization: Bearer $GENKILN_API_KEY"The task object
JSON
{
"id": "task_01JC8ZQ0E6H2P4N7K9T3W5Y8VA",
"object": "task",
"model": "veo-3.1-fast",
"status": "succeeded",
"cost_credits": 390,
"refunded": false,
"output": {
"images": [],
"videos": [
{ "url": "https://cdn.genkiln.com/results/.../0.mp4", "duration": 8 }
]
},
"error": null,
"created_at": "2026-11-03T08:00:00.000Z",
"started_at": "2026-11-03T08:00:09.000Z",
"completed_at": "2026-11-03T08:01:12.000Z",
"expires_at": "2026-12-03T08:01:12.000Z",
"metadata": { "order_id": "abc123" }
}| Field | Type | Description |
|---|---|---|
id | string | Task ID, task_ followed by 26 characters. IDs sort by creation time. |
object | string | Always task. |
model | string | The model ID you requested. |
status | string | queued, processing, succeeded, failed or canceled. See below. |
cost_credits | integer | Credits charged for this task when it was created. |
refunded | boolean | true once the charge has been returned to your balance (failed or canceled tasks). |
output | object | null | Set only when status is succeeded: images and videos arrays of { url }. Videos also carry duration (seconds) when the model takes one. |
error | object | null | { code, message } when the task failed or was canceled, otherwise null. |
created_at | string | ISO 8601 timestamp (UTC). |
started_at | string | null | When generation started. |
completed_at | string | null | When the task reached a final status. |
expires_at | string | null | For succeeded tasks: when the output files are deleted, 30 days after completed_at. |
metadata | object | The metadata you sent, or {}. |
Statuses
| Status | Final | Meaning |
|---|---|---|
queued | No | Accepted and waiting to start. |
processing | No | Generating, or saving the result files. |
succeeded | Yes | Done. output holds the result URLs. |
failed | Yes | Did not complete. error says why; credits are refunded (refunded: true). |
canceled | Yes | Stopped by us, for example when a model is withdrawn. Credits are refunded. |
A final status never changes again. A task stays processing until its files are saved, so the URLs in output always work once you see succeeded.
Task error codes
| `error.code` | Meaning |
|---|---|
generation_failed | Generation failed. |
content_rejected | The prompt or input media was rejected by our content policy. |
invalid_input | The input could not be processed, for example an image URL that cannot be downloaded. |
timeout | The task did not finish in time (15 minutes for images, 45 minutes for videos, counted from created_at). |
service_busy | The service was temporarily busy. Retry shortly. |
canceled | The task was canceled. |
Every failed or canceled task is refunded, whatever the code.
Output files
- Result URLs are on
https://cdn.genkiln.comand need no authentication. Anyone with the URL can download the file, and URLs are not guessable. - Files are kept for 30 days after the task completes (
expires_at), then deleted. Copy anything you need to your own storage. - Formats: images are PNG, JPEG or WebP; videos are MP4 or WebM.
Polling
Poll every 3 to 10 seconds for images and every 10 to 30 seconds for videos, and stop at a final status. Reads count toward the query rate limit. For many tasks, webhooks are cheaper than polling.