multipartUpload

Retrieve the status of an upload session

Changed on

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 endpoint until the status of the asset is ready before you use it.

get/assets/multipart-uploads/{upload_id}

Request

  • Base URL: https://api.twelvelabs.io/v1.3
  • URL: https://api.twelvelabs.io/v1.3/assets/multipart-uploads/{upload_id}
  • Auth: API key in header x-api-key

Path parameters

upload_idstring required

The unique identifier of the upload session.

Query parameters

pageinteger

A number that identifies the page to retrieve.

Default: 1.

page_limitinteger

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.

status'active' | 'completed' | 'failed' | 'expired'

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.
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.

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_atstring date-time

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

updated_atstring date-time

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

Changes

  • b8591e05c0baRevision changes
    • warning

      deleted the header request parameter x-api-key

    • info

      the endpoint scheme security x-api-key was added to the API

  • 6205c7327cdeRevision changes
    • info

      api operation id get-status removed and replaced with multipartUpload_get_status