> ## Documentation Index > Fetch the complete documentation index at: https://docs.gumnut.ai/llms.txt > Use this file to discover all available pages before exploring further. # Get task status > 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. ## OpenAPI ````yaml https://api.gumnut.ai/openapi.json get /api/tasks/{task_id} openapi: 3.1.0 info: title: Gumnut API description: >- The Gumnut API manages photo and video libraries: upload and organize assets, search by content, group detected faces into people, and curate albums and stacks. Headless clients authenticate by sending either a Gumnut API key (`apikey_...`) or an OAuth access token as a Bearer token in the `Authorization` header. The Gumnut web and mobile apps sign in with a first-party session (Clerk session JWT) instead, which is also the only credential that can manage API keys. contact: name: Gumnut url: https://www.gumnut.ai/contact version: 1.0.0 servers: - url: https://api.gumnut.ai description: Production security: - apiKeyAuth: [] - oauthJwtAuth: [] tags: - name: assets description: >- Photos and videos in a library: upload, list and filter, update metadata, trash and restore. - name: search description: >- Content-based search over a library's assets, with the same filters as asset listing. - name: albums description: User-curated collections of assets. - name: album-assets description: Link records connecting albums to their member assets. - name: stacks description: >- Groups of related shots of the same moment, presented as a single unit with a cover asset. - name: people description: Named people, each built from clustered faces. - name: faces description: Detected faces and their assignment to people. - name: libraries description: Top-level containers that own assets, albums, people, and everything else. - name: events description: Change-event feed for keeping client state in sync. - name: tasks description: Status of background processing tasks. - name: users description: The authenticated user's profile. - name: api-keys description: >- Create and manage Gumnut API keys. Requires a first-party Gumnut app session — API keys and OAuth tokens cannot manage credentials. - name: oauth description: OAuth flow endpoints for obtaining and refreshing access tokens. - name: server description: Service health. paths: /api/tasks/{task_id}: get: tags: - tasks summary: Get task status description: |- 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. operationId: get_task_status parameters: - name: task_id in: path required: true schema: type: string description: >- Task identifier — either the task's `id` or its `celery_task_id`; both are accepted. title: Task Id description: >- Task identifier — either the task's `id` or its `celery_task_id`; both are accepted. responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/TaskResponse' '401': description: Missing, invalid, or expired credentials. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: >- 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. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Task not found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' '429': description: >- Rate limit exceeded. Retry after the interval in the `Retry-After` header. headers: Retry-After: description: Seconds to wait before retrying. schema: type: integer content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' components: schemas: TaskResponse: properties: id: type: string title: Id description: Unique task identifier with `btask_` prefix asset_id: anyOf: - type: string - type: 'null' title: Asset Id description: >- ID of the asset this task processes; null for library-scoped tasks such as face clustering task_type: $ref: '#/components/schemas/TaskType' celery_task_id: type: string title: Celery Task Id description: >- Application-generated delivery identifier supplied to the task queue. Also accepted by `get_task_status` in place of `id`. status: $ref: '#/components/schemas/TaskStatus' result: anyOf: - type: string - type: 'null' title: Result description: Result summary produced by a completed task; null until success error_message: anyOf: - type: string - type: 'null' title: Error Message description: >- 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: type: integer title: Retry Count description: >- 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: type: string title: Created At description: >- When the task record was created (ISO 8601); dispatch to the task queue follows separately, after the creating transaction commits started_at: anyOf: - type: string - type: 'null' title: Started At description: >- 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: anyOf: - type: string - type: 'null' title: Completed At description: >- When the task finished, whether successfully or not (ISO 8601); null until then type: object required: - id - asset_id - task_type - celery_task_id - status - result - error_message - retry_count - created_at - started_at - completed_at title: TaskResponse description: A background processing task and its current execution state. ErrorResponse: title: ErrorResponse type: object properties: detail: title: Detail type: string description: Human-readable explanation of the error. required: - detail HTTPValidationError: properties: detail: items: $ref: '#/components/schemas/ValidationError' type: array title: Detail type: object title: HTTPValidationError TaskType: type: string enum: - 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 title: TaskType description: >- 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). TaskStatus: type: string enum: - pending - started - success - failure title: TaskStatus description: |- 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). ValidationError: properties: loc: items: anyOf: - type: string - type: integer type: array title: Location msg: type: string title: Message type: type: string title: Error Type input: title: Input ctx: type: object title: Context type: object required: - loc - msg - type title: ValidationError securitySchemes: apiKeyAuth: type: http scheme: bearer description: >- Gumnut API key (`apikey_...`) sent as a Bearer token in the `Authorization` header. Create and manage keys in the Gumnut app, or with the API key endpoints while signed in to it. oauthJwtAuth: type: http scheme: bearer bearerFormat: JWT description: >- Short-lived JWT obtained from the OAuth token exchange, sent as a Bearer token in the `Authorization` header. ````