API ReferenceUpload contentMultipart uploads

Retrieve the status of an upload session

This method provides information about an upload session, including its current status, chunk-level progress, and completion state. Use this method to: - Verify upload completion (`status` = `completed`) - Identify any failed chunks that require a retry - Monitor the upload progress by comparing `uploaded_size` with `total_size` - Determine if the session has expired - Retrieve the status information for each chunk After you report chunk completion, call this method to confirm the upload session reached the `completed` status. This status means the platform received the file, not that the asset is ready to use. The platform then validates the asset asynchronously. Poll the [Retrieve an asset](/v1.3/api-reference/upload-content/direct-uploads/retrieve) endpoint until the status of the asset is `ready` before you use it.

Authentication

x-api-keystring
Your API key. <Note title="Note"> You can find your API key on the <a href="https://playground.twelvelabs.io/dashboard/api-keys" target="_blank">API Keys</a> page. </Note>

Path parameters

upload_idstringRequired
The unique identifier of the upload session.

Query parameters

pageintegerOptionalDefaults to 1

A number that identifies the page to retrieve.

Default: 1.

page_limitintegerOptionalDefaults to 10

The number of items to return on each page.

Default: 10. Max: 50.

Response

The status of your upload session has been successfully retrieved.
upload_idstring
The unique identifier of your upload session.
statusenum

The status of your upload session. This field can take one of the following values:

  • active: The upload session is currently in progress. Continue uploading and reporting the completion of each chunk.
  • completed: The platform received the file. The asset is created in the processing status and is not yet ready to use. Poll the Retrieve an asset endpoint until the status of the asset is ready before you use it.
  • failed: The upload session failed. You must restart with a new session.
  • expired: The upload session expired after 24 hours. You must create a new session.
uploaded_chunkslist of objects
Detailed status for each chunk.
chunks_completedinteger

The number of chunks successfully uploaded and reported. When this value equals total_chunks, the status of your upload session transitions to completed.

chunks_failedinteger

The number of chunks that failed to upload. If the number is greater than 0, check the uploaded_chunks array for specific failures and retry those chunks.

chunks_pendinginteger

The number of chunks not yet successfully uploaded. This value is calculated as: total_chunks - chunks_completed - chunks_failed.

page_infoobject
An object that provides information about pagination.
total_sizeinteger
The size of your file in bytes. You provided this value when you created the upload session.
uploaded_sizeinteger
The number of bytes successfully uploaded
created_atstringformat: "date-time"

A string representing the date and time, in RFC 3339 format (“YYYY-MM-DDTHH:mm:ssZ”), when the resource was created.

updated_atstringformat: "date-time"

A string representing the date and time, in RFC 3339 format (“YYYY-MM-DDTHH:mm:ssZ”), when the resource was last updated.

Errors

400
Bad Request Error
403
Forbidden Error
404
Not Found Error
500
Internal Server Error