---
title: "Get task status"
method: GET
path: "/api/tasks/{task_id}"
tags: ["tasks"]
---

# Get task status

`GET /api/tasks/{task_id}`

Get the status of a background task by its ID.

Returns 404 if no task with the given identifier exists among the
authenticated user's libraries.

## Path parameters

- `task_id` string, required — Task identifier — either the task's `id` or its `celery_task_id`; both are accepted.

## Response `200`

Successful Response

- TaskResponse — A background processing task and its current execution state.
  - `id` string, required — Unique task identifier with `btask_` prefix
  - `asset_id` string, nullable, required — ID of the asset this task processes; null for library-scoped tasks such as face clustering
  - `task_type` 'image_quality' | 'embedding' | 'face_detection' | 'face_clustering' | 'asset_description' | 'asset_storage_cleanup' | 'asset_version_storage_cleanup' | 'reverse_geocoding' | 'video_thumbnail_extract' | 'video_metadata_extract' | 'thumbhash' | 'display_proxy_generation' | 'burst_detection', required — Kind of background processing a task performs: `image_quality` (historical only — scored an image's technical quality; this task type is retired and no longer dispatched, the value appears only on old task rows), `embedding` (compute the content embedding that powers search), `face_detection` (detect faces in an asset), `face_clustering` (group a library's detected faces into people), `asset_description` (generate a natural-language description of an asset), `asset_storage_cleanup` (remove stored files left behind by a permanently deleted asset), `asset_version_storage_cleanup` (remove stored files of a superseded asset version), `reverse_geocoding` (resolve an asset's GPS coordinates to a place name), `video_thumbnail_extract` (extract a thumbnail image from a video), `video_metadata_extract` (recover a video's capture time, GPS location, and camera details from the file's own metadata), `thumbhash` (compute the blurred placeholder shown while a thumbnail loads), `display_proxy_generation` (generate a browser-displayable rendition of an original the image CDN cannot transform, such as an oversized or over-dimensioned file), or `burst_detection` (detect rapid-fire shots of the same moment and stack them).
  - `celery_task_id` string, required — Application-generated delivery identifier supplied to the task queue. Also accepted by `get_task_status` in place of `id`.
  - `status` 'pending' | 'started' | 'success' | 'failure', required — Status of a background task execution: `pending` (created and awaiting processing), `started` (picked up by a worker and not yet in a terminal state — the task may be executing or awaiting an automatic retry after a transient failure), `success` (completed successfully), or `failure` (failed and will not be retried).
  - `result` string, nullable, required — Result summary produced by a completed task; null until success
  - `error_message` string, nullable, required — Error detail from the most recent failed or retried attempt; not cleared by a later success, so it can be non-null on a task that failed transiently and then succeeded. Null if no attempt has failed
  - `retry_count` integer, required — Retry and rescue bookkeeping value for this task. Zero before any automatic retry or stuck-task rescue; not guaranteed to be a cumulative delivery count
  - `created_at` string, required — When the task record was created (ISO 8601); dispatch to the task queue follows separately, after the creating transaction commits
  - `started_at` string, nullable, required — When a worker most recently began executing the task, or when the stuck-task reaper rescued it back to pending (ISO 8601). Because a rescue can re-enqueue a task no worker ever picked up, a non-null value does not prove a worker has run the task
  - `completed_at` string, nullable, required — When the task finished, whether successfully or not (ISO 8601); null until then

## Other responses

- `401` — Missing, invalid, or expired credentials.
- `403` — The credentials are valid but not authorized for this operation — for example an API key whose action or library scope excludes it, or a credential type this operation does not accept.
- `404` — Task not found
- `422` — Validation Error
- `429` — Rate limit exceeded. Retry after the interval in the `Retry-After` header.

---

[API](https://skmtc.net/gumnut-ai/apis/gumnut-api.md) · [All operations](https://skmtc.net/gumnut-ai/apis/gumnut-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/gumnut-ai/gumnut-api/versions/e71db45f5d4a/schema)