ListTables

Usage notes

Note

This API supports only Iceberg tables, not Lance tables. To list Lance tables, use the Lance REST Namespace API or the Lance ecosystem (Spark, Trino, and other compute engines).

A single request returns up to 1,000 tables. Use continuationToken for pagination.
Use the namespace parameter to list tables within a specific namespace.
Use the prefix parameter to filter by table name prefix.

Permissions

API	Action	Description
ListTables	oss:ListTables	List tables.

Request syntax

GET /tables/{tableBucketARN} HTTP/1.1
Host: cn-hangzhou.oss-tables.aliyuncs.com
Date: GMT Date
Authorization: SignatureValue

Request parameters

Parameter	Type	Required	Example value	Description
tableBucketARN	String	Yes	acs:osstables:cn-hangzhou:1234567890:bucket/my-table-bucket	The Table Bucket ARN, specified in the request URI. Format: `acs:osstables:{region}:{uid}:bucket/{bucketName}`.
continuationToken	String	No	xxx-continuation-token	Pagination token from the previous response. Omit for the initial request. Query parameter.
maxTables	Integer	No	100	Maximum number of tables to return. Valid values: 1 to 1,000. Default: 1,000. Query parameter.
namespace	String	No	my_namespace	Returns only tables in the specified namespace. Query parameter.
prefix	String	No	my_	Returns only tables whose names start with this prefix. Query parameter.

Response parameters

Parameter	Type	Example value	Description
tables	Array	-	List of table objects. Each contains: `name` (table name), `namespace` (array of namespace names), `tableARN` (table ARN), `type` (table type), `createdAt` (creation time), and `modifiedAt` (last modification time).
continuationToken	String	xxx-continuation-token	Returned only when results are truncated. Pass this value in a subsequent request to retrieve the next page.

Examples

Request example

GET /tables/acs%3Aosstables%3Acn-hangzhou%3A1234567890%3Abucket%2Fmy-table-bucket?namespace=my_namespace HTTP/1.1
Host: cn-hangzhou.oss-tables.aliyuncs.com
Date: Thu, 10 Apr 2025 08:00:00 GMT
Authorization: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-hangzhou/osstables/aliyun_v4_request,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c****

Response example

HTTP/1.1 200 OK
Server: AliyunOSS
x-oss-request-id: 5C06A3B67B8B5A3DA422****
x-oss-server-time: 3
Content-Type: application/json


{
   "continuationToken": "xxxxx",
   "tables": [
      {
         "name": "my_table",
         "namespace": ["my_namespace"],
         "tableARN": "acs:osstables:cn-hangzhou:1234567890:bucket/my-table-bucket/table/table_id",
         "type": "customer",
         "createdAt": "2024-01-01T00:00:00.000000Z",
         "modifiedAt": "2024-06-01T00:00:00.000000Z"
      }
   ]
}

SDKs

ListTables is available in the following SDKs:

ossutil CLI

Corresponding ossutil command: list-tables.

Error codes

Error code	HTTP status code	Description
BadRequestException	400	The request is invalid or malformed.
ForbiddenException	403	The caller lacks the required permission.
NotFoundException	404	The requested resource does not exist.