--- title: "Get asset tasks" method: GET path: "/api/tasks/asset/{asset_id}" tags: ["tasks"] --- # Get asset tasks `GET /api/tasks/asset/{asset_id}` ## Request - Base URL: `https://api.gumnut.ai` - URL: `https://api.gumnut.ai/api/tasks/asset/{asset_id}` - Auth: one of: - HTTP bearer - HTTP bearer - TypeScript: (a function with typed inputs; its response is checked against the schema) Get all background tasks for a specific asset. Results are ordered newest first. ## Path parameters - `asset_id` string, required: ID of the asset whose tasks to return ## Response `200` Successful Response - TaskResponse[] - `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` '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' | 'product_update_subscription' | 'person_metrics_refresh' | 'quality_scoring', required: Kind of background processing a task performs: `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), `burst_detection` (detect rapid-fire shots of the same moment and stack them), `product_update_subscription` (enroll an explicitly opted-in new user in product-update email delivery), `person_metrics_refresh` (recompute the face-matching summary of one person after their faces change), or `quality_scoring` (rate an image's photographic quality). - `celery_task_id` string, required: Deprecated alternate task identifier. Use `id` instead. - `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 - `outcome` string, nullable, required: Stable outcome code whose meaning depends on `task_type`. For a successful `face_detection` task: `ran` means detection ran, possibly finding no faces; `skipped_photo_location` means automatic detection is not offered at the photo's location; `skipped_location_unread` means the photo has no location and its file's metadata has not been read; `skipped_owner_off` means the library owner had not turned detection on when the photo was processed; `skipped_owner_region` means detection is not offered in the owner's home region. Turning detection on later does not process earlier photos. Null for other task types, tasks that have not succeeded, and skips with no explanation, such as files that are not images. Each task reports its own run. Codes may be added for any task type; treat an unrecognized code as no explanation. - `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. - `409`: Clerk sign-in could not be associated with the existing account. Resolve the identity conflict before retrying sign-in; repeated requests with unchanged verification and identity state will not resolve it. - `422`: Validation Error - `429`: Rate limit exceeded, or too many of your requests are already in progress. Retry after the interval in the `Retry-After` header. - `503`: Authentication provider temporarily unavailable. Retry sign-in later. ## Changes - **2026-10-20** `4dcbf19e1db8`: 2 info - removed the `face_template_removal` enum value from the `items/task_type` response property for the response status `200` - removed the `image_quality` enum value from the `items/task_type` response property for the response status `200` - **2026-10-16** `340daf103f92`: 2 info - response property `items/celery_task_id` deprecated - added the required property `items/outcome` to the response with the `200` status - **2026-10-16** `7c2860d9eb88`: 3 warning, 2 info - added the new `face_template_removal` enum value to the `items/task_type` response property for the response status `200` - added the new `person_metrics_refresh` enum value to the `items/task_type` response property for the response status `200` - added the new `quality_scoring` enum value to the `items/task_type` response property for the response status `200` - added the non-success response with the status `409` - …1 more - **2026-08-17** `cd15387eb365`: 1 warning - added the new `product_update_subscription` enum value to the `items/task_type` response property for the response status `200` - **2026-08-08** `815e0302a988`: 1 breaking, 1 info - response property `detail` list-of-types was widened by adding types `string` to media type `application/json` of response `422` - the response property `detail` became required for the status `422` [Operation history](https://skmtc.dev/gumnut-ai/apis/gumnut-api/changes/api/tasks/asset/:asset_id/get.md) --- [API](https://skmtc.dev/gumnut-ai/apis/gumnut-api.md) - [All operations](https://skmtc.dev/gumnut-ai/apis/gumnut-api/llms.txt) - [OpenAPI document](https://skmtc.dev/gumnut-ai/apis/gumnut-api/revisions/bde647a9e5a6?raw)