---
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_uncertainty` number[] — A per-dimension uncertainty vector with the same length as the `embedding` array. A higher value shows lower confidence in that dimension. Present when the request sets [`embedding_uncertainty: true`](/v1.3/api-reference/create-embeddings-v2/create-embeddings#request.body.embedding-uncertainty). Only Marengo 3.5 returns this field.
    - `embedding_option` 'visual' | 'audio' | 'transcription' | 'text' | 'fused' — The modality used to generate this embedding. **Values**: - `visual`: Embedding based on visual content (a video, a page of a PDF file, or an image embedded asynchronously). - `audio`: Embedding based on audio content. - `text`: The platform does not return this value. - `transcription`: Embedding based on transcribed speech. Returned only for content embedded with Marengo 3.0. - `fused`: Embedding based on a combination of the modalities specified in the request. The platform returns this embedding only for video and audio input, and only when the `embedding_type` parameter includes the `fused_embedding` value. - `null`: For text embeddings and images embedded synchronously.
    - `embedding_scope` 'clip' | 'page' | 'asset' — The scope for which the embedding was generated. **Values**: - `clip`: Embedding for a segment. For video and audio input, one embedding per detected segment. - `page`: Embedding for one page of a document. The platform returns this value only for PDF files embedded asynchronously. - `asset`: Embedding for the entire file. For video and audio input, use this scope for content up to 10-30 seconds to maintain optimal performance. - `null`: For text embeddings and images embedded synchronously. When you request the `local` scope, the platform returns `clip` for audio and video, and `page` for PDF files. For audio, video, and document input, the `metadata.embedding_scopes` field contains the scopes you requested.
    - `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.
    - `start_page_number` integer, nullable — The first page this embedding covers, counting from 1. The platform returns this field only for page-level embeddings of a PDF file, and `null` in every other case.
    - `end_page_number` integer, nullable — The last page this embedding covers, counting from 1 and including that page. This field matches the `start_page_number` field when the embedding covers a single page. The platform returns this field only for page-level embeddings of a PDF file, and `null` in every other case.
  - `usage` EmbeddingUsage — Token counts for the request. Only Marengo 3.5 returns this object.
    - `input_tokens` object, required — The number of tokens the request used. Each key names a type of content the request processed, and each value is the token count for that content.
    - `truncated` boolean, required — Whether the input was truncated to fit within the token limit.
  - `metadata` union — Metadata for the media input.
    - object — Metadata for audio embeddings.
      - `input_type` 'audio' | 'video' | 'document' | 'image', 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 — The `embedding_option` values used to generate the embedding.
      - `embedding_scopes` EmbeddingAudioMetadataEmbeddingScopesItems[], required — The `embedding_scope` values used to generate the embedding.
      - `duration` number, double, required — The duration of the audio in seconds.
      - `start_offset_sec` number, double — The start offset in seconds.
      - `end_offset_sec` number, double — The end offset in seconds.
    - object — Metadata for video embeddings.
      - `input_type` 'audio' | 'video' | 'document' | 'image', 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 — The `embedding_scope` values used to generate the embedding.
      - `embedding_options` string[], required — The `embedding_option` values used to generate the embedding.
      - `duration` number, double, required — The duration of the video in seconds.
      - `start_offset_sec` number, double — The start offset in seconds.
      - `end_offset_sec` number, double — The end offset in seconds.
    - object — Metadata for document embeddings. Only Marengo 3.5 returns this object.
      - `input_type` 'audio' | 'video' | 'document' | 'image', required
      - `input_url` string — The publicly accessible URL for the document file.
      - `input_filename` string — The name of the document file.
      - `embedding_options` string[] — The `embedding_option` values used to generate the embedding.
      - `embedding_scopes` AsyncDocumentMetadataEmbeddingScopesItems[] — The `embedding_scope` values used to generate the embedding.
    - object — Metadata for image embeddings. Only Marengo 3.5 returns this object.
      - `input_type` 'audio' | 'video' | 'document' | 'image', required
      - `input_url` string — The publicly accessible URL for the image file.
      - `input_filename` string — The name of the image file.
      - `embedding_options` string[] — The `embedding_option` values used to generate the embedding. Always `["visual"]`.
      - `embedding_scopes` AsyncImageMetadataEmbeddingScopesItems[] — The `embedding_scope` values used to generate the embedding. Always `["asset"]`.
  - `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

## Changes

- **2026-09-01** `8bb2e6eb62e8` — 1 breaking, 2 warning, 5 info
  - added `subschema #1, subschema #2, subschema #3, subschema #4` to the `metadata` response property `oneOf` list for the response status `200`
  - added the new `page` enum value to the `data/items/embedding_scope/oneOf[subschema #1: EmbeddingDataEmbeddingScope]/` response property for the response status `200`
  - added the new `text` enum value to the `data/items/embedding_option/oneOf[subschema #1: EmbeddingDataEmbeddingOption]/` response property for the response status `200`
  - added the optional property `data/items/embedding_uncertainty` to the response with the `200` status
  - …4 more
- **2026-07-26** `c0926990c662` — 1 breaking, 2 info
  - added `subschema #1, subschema #2` to the `metadata` response property `oneOf` list for the response status `200`
  - added discriminator to `metadata` response property for the response status `200`
  - removed `#/components/schemas/EmbeddingAudioMetadata, #/components/schemas/EmbeddingVideoMetadata` from the `metadata` response property `oneOf` list for the response status `200`

[Change history](https://skmtc.dev/twelvelabs/apis/twelvelabs-api/changes/embed-v2/tasks/:task_id/get.md)

---

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