Docs

Torch Object Storage

FAQ

API FAQ

Category	FAQ
Directory operations	How can I tell if an object is a directory? How can I list directories via API? Does TOS offer APIs for uploading, downloading, or deleting directories?
Object query and listing	How can I find out how many objects a directory contains and what its size is? Does the ListObjects API support listing in descending order? How can I check if an object has changed via API?
Object read/write and modification	Does the CopyObject API consume bandwidth quotas? Is it idempotent? Does the GetObject API support retrieving a byte range from an object by specifying an offset and a length? How can I rename an object via API? How can I change an object's storage type via API?
Object migration and copying	How can I copy an object from one bucket/account to another bucket/account via API?
Pre-signed URLs	Why do I receive a 403 error when making a TOS API request with a pre-signed URL? How long is a pre-signed URL valid?

Directory operations

How can I tell if an object is a directory?

There are no directories in object storage. Objects are stored in a flat organization. To simulate directories, an object whose name ends in a slash (/) is considered a directory, regardless of its size.

How can I list directories via API?

There are no directories in object storage. An object whose name ends in a slash (/) is considered a directory, regardless of its size. When using the TOS API to list objects, you can pass the delimiter parameter to simulate listing by directory.

After you set the delimiter, the API's response will include the following information:

An array called CommonPrefixes that represents the set of subdirectories.

An array called Contents that represents the set of objects directly under the current directory.

You can then use each subdirectory in the CommonPrefixes array as the prefix to recursively list objects and subdirectories. For more information, see ListObjects.

Does TOS offer APIs for uploading, downloading, or deleting directories?

Since there are no directories in object storage, TOS does not have dedicated APIs for these operations. If you need to perform these operations, you can implement them using the following APIs:

To upload a directory, combine ListObjects and PutObject.

To download a directory, combine ListObjects and GetObject.

To delete a directory, combine ListObjects and DeleteObject.

Object query and listing

How can I find out how many objects a directory contains and what its size is?

Since there are no directories in object storage, TOS does not provide an API for this information. If you need this information, you can use the ListObjects API to calculate the size and file count of a directory recursively. For more information, see ListObjects.

Does the ListObjects API support listing in descending order?

No. It only supports listing objects in lexicographically ascending order by object name, using a prefix and a delimiter (typically /).

How can I check if an object has changed via API?

TOS provides the HeadObject API for querying object metadata. If an object exists, the response headers will include an ETag, which is a hash of the object data, as well as a Last-Modified header indicating the last modified time.

When using GetObject or CopyObject, you can use the HTTP conditional headers "If-Match" or "If-Unmodified-Since" to ensure the operation only occurs if the object has not changed.

Object read/write and modification

Does the CopyObject API consume bandwidth quotas? Is it idempotent?

The CopyObject API uses its own private network bandwidth, so it does not affect your read/write bandwidth quotas. Additionally, the API is idempotent, so retrying due to a client timeout will not result in data corruption.

Does the GetObject API support retrieving a byte range from an object by specifying an offset and a length?

Yes. It supports the standard HTTP Range GET, which allows you to retrieve a portion of an object using the Range: bytes=x-y header. For more information, see GetObject.

How can I rename an object via API?

Currently, TOS does not provide an API for this. To rename an object, first call CopyObject, and then call DeleteObject. However, for objects larger than 5 GB, CopyObject alone will not suffice. In this case, you will need to use the multipart copy approach via UploadPartCopy.

How can I change an object's storage type via API?

For objects smaller than 5 GiB, use CopyObject.

For objects larger than 5 GiB, use CreateMultipartUpload, UploadPartCopy, or CompleteMultipartUpload.

Object migration and copying

How can I copy an object from one bucket/account to another bucket/account via API?

To copy objects within regions, we recommend using CopyObject or UploadPartCopy directly. The differences are as follows:

CopyObject only supports objects smaller than 5 GiB.

UploadPartCopy supports objects larger than 5 GiB through multipart copying.

To copy objects across regions, combine GetObject and PutObject/UploadPart to read from the source and write to the destination.

warning

To copy within or between regions, make sure you have read permission for the source bucket and write permission for the destination bucket.

Pre-signed URLs

Why do I receive a 403 error when making a TOS API request with a pre-signed URL?

A 403 error usually indicates an inconsistency between the key fields used to generate the signature and the fields in the actual HTTP request. These fields may include the HTTP method (GET, HEAD, PUT, POST, or DELETE), request query parameters, or request headers. For more information, see Including a signature in the URL.

How long is a pre-signed URL valid?

TOS servers support pre-signed URLs with a maximum validity period of seven days. Learn how in Including a signature in the URL. We recommend using the PreSignedURL function in the TOS SDK to generate pre-signed URLs.

Last updated: 2026.06.22 15:21:16