---
title: "Retrieve task status and results"
method: GET
path: "/embed-v2/tasks/{task_id}"
tags: ["embed > v2 > tasks"]
---

# Retrieve task status and results

`GET /embed-v2/tasks/{task_id}`

This method retrieves the status and the results of an async embedding task.

Invoke this method repeatedly until the `status` field is `ready` or `failed`. When the status is `ready`, use the embeddings from the response. When the status is `failed`, the `error.message` field contains the reason.

<Note title="Note">
Embeddings are stored for seven days.
</Note>

## Path parameters

- `task_id` string, required

## Headers

- `x-api-key` string, required

## Response `200`

Task status and results retrieved successfully

- EmbeddingTaskResponse — An object containing the status of the embedding task and the embeddings (when ready).
  - `_id` string, required — The unique identifier of the embedding task.
  - `status` 'processing' | 'ready' | 'failed', required — The current status of the task. **Values**: - `processing`: The platform is creating the embeddings - `ready`: Processing is complete. Embeddings are available in the `data` field - `failed`: The task failed. The `data` field is `null`, and the [`error.message`](/v1.3/api-reference/create-embeddings-v2/retrieve-embeddings#response.body.error.message) field contains the reason
  - `created_at` string, date-time — A string representing the date and time, in RFC 3339 format (“YYYY-MM-DDTHH:mm:ssZ”), when the resource was created.
  - `updated_at` string, date-time — A string representing the date and time, in RFC 3339 format (“YYYY-MM-DDTHH:mm:ssZ”), when the resource was last updated.
  - `data` EmbeddingData[], nullable, required — An object containing the embedding results, or `null` otherwise.
    - `embedding` number[], required — The embedding vector for the content.
    - `embedding_option` 'visual' | 'audio' | 'transcription' | 'fused' — The modality used to generate this embedding. **Values**: - `visual`: Embedding based on visual content (video only) - `audio`: Embedding based on audio content - `transcription`: Embedding based on transcribed speech - `fused`: Embedding based on a combination of the modalities specified in the request. The platform returns this embedding only for video and audio content, and only when the `embedding_type` parameter in the request includes `fused_embedding`. - `null`: For text and image embeddings
    - `embedding_scope` 'clip' | 'asset' — The scope for which the embedding was generated. **Values**: - `clip`: Embedding for a segment - `asset`: Embedding for the entire file. Use this scope for videos up to 10-30 seconds to maintain optimal performance. - `null`: For text and image embeddings
    - `start_sec` number, double, nullable — The start time in seconds for this segment. This field is `null` for text and image embeddings.
    - `end_sec` number, double, nullable — The end time in seconds for this segment. This field is `null` for text and image embeddings.
  - `metadata` union — Metadata for the media input.
    - object — Metadata for audio embeddings
      - `input_type` 'audio' | 'video', required
      - `input_url` string — The publicly accessible URL for the audio file
      - `input_filename` string — The name of the audio file
      - `embedding_options` string[], required — Audio embedding options used for generating the embedding
      - `embedding_scopes` EmbeddingAudioMetadataEmbeddingScopesItems[], required — Audio embedding scopes
      - `duration` number, double, required — Duration of the audio in seconds
      - `start_offset_sec` number, double — Start offset in seconds
      - `end_offset_sec` number, double — End offset in seconds
    - object — Metadata for video embeddings
      - `input_type` 'audio' | 'video', required
      - `input_url` string — The publicly accessible URL for the video file
      - `input_filename` string — The name of the video file
      - `clip_length` integer — Length of each video clip in seconds. Only available for fixed segmentation.
      - `embedding_scopes` EmbeddingVideoMetadataEmbeddingScopesItems[], required — Video embedding scopes
      - `embedding_options` string[], required — Video embedding options used for generating the embedding
      - `duration` number, double, required — Duration of the video in seconds
      - `start_offset_sec` number, double — Start offset in seconds
      - `end_offset_sec` number, double — End offset in seconds
  - `error` EmbeddingTaskResponseError — An object describing why the embedding task failed. Present only when `status` is `failed`. Omitted otherwise.
    - `message` string, required — A human-readable message that describes why the task failed. Possible values: - "The embedding service is temporarily unstable. Please try again later." - "The embedding task failed. Please try again later." - "We could not process your media for embedding. Please verify the input file and try again." For the steps to fix the file, see the [How do I fix a file that could not be processed for embedding?](/v1.3/docs/resources/frequently-asked-questions#how-do-i-fix-a-file-that-could-not-be-processed-for-embedding) section on the **Frequently asked questions** page.

## Other responses

- `404` — Task not found

---

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