---
title: "Tables in bucket"
method: GET
path: "/v2/storage/branch/{branchId}/buckets/{bucketId}/tables"
tags: ["Tables"]
---

# Tables in bucket

`GET /v2/storage/branch/{branchId}/buckets/{bucketId}/tables`

## Request

- Base URL: `https://connection.keboola.com`
- URL: `https://connection.keboola.com/v2/storage/branch/{branchId}/buckets/{bucketId}/tables`
- Auth: one of:
  - API key in header `X-StorageApi-Token`
  - API key in header `X-KBC-ManageApiToken`
  - HTTP bearer
- TypeScript: <https://skmtc.dev/keboola/apis/keboola-storage-api/docs/v2/storage/branch/:branchId/buckets/:bucketId/tables/get.ts> (a function with typed inputs; its response is checked against the schema)

Lists tables in a given bucket. By default each table is returned with its attributes and metadata;
use the `include` query parameter to add columns, column metadata or (for aliases) source table metadata.

## Path parameters

- `bucketId` string, required
- `branchId` string, required

## Query parameters

- `include` string

## Response `200`

List of tables in the bucket.

- TableListItemResponse[]
  - `uri` string, required: Table detail URI
  - `id` string, required: Table identifier
  - `name` string, required: Table name
  - `displayName` string, required: Display name of the table
  - `transactional` boolean, required: Transactional flag
  - `primaryKey` string[], required
  - `indexType` string, nullable, required
  - `indexKey` string[], required
  - `distributionType` string, nullable, required
  - `distributionKey` string[], required
  - `syntheticPrimaryKeyEnabled` boolean, required
  - `created` string, nullable, required: Created timestamp, ISO 8601 with a `+hhmm` offset.
  - `lastImportDate` string, nullable, required: Last import date, ISO 8601 with a `+hhmm` offset.
  - `lastChangeDate` string, nullable, required: Last change date, ISO 8601 with a `+hhmm` offset.
  - `rowsCount` integer, nullable, required
  - `dataSizeBytes` integer, nullable, required
  - `isAlias` boolean, required
  - `isAliasable` boolean, required
  - `isTyped` boolean, required
  - `isDescriptionSystemManaged` boolean, required: True when the table description is managed by the system.
  - `timestampType` 'MANAGED' | 'SELFMANAGED' | 'NONE', required: How the `_timestamp` column is managed.
  - `tableType` string, required
  - `path` string, required
  - `attributes` object[]: Always an empty array, kept for backward compatibility. Present with `include=attributes` (the default).
  - `columns` string[]: Column names. Present with `include=columns`.
  - `bucket` TableBucketResponse: The bucket a table lives in, as embedded in table responses. Built by Model_Row_Bucket::toApiResponse() and extended with `metadata` by the table response provider. Unlike the standalone bucket detail response, `tables` here is the bucket URI, not a list of table objects, and there is no `scheduledTasks`, `listing` or `linkedBy`.
    - `uri` string, required: API URI of the bucket.
    - `id` string, required: Bucket identifier (`{stage}.{name}`).
    - `name` string, required: Bucket name (prefixed with `c-`).
    - `displayName` string, required: Human-readable display name shown in the UI.
    - `idBranch` integer, required: ID of the branch the bucket belongs to.
    - `stage` 'in' | 'out' | 'sys', required: Bucket stage.
    - `description` string, required: Bucket description.
    - `tables` string, required: The same URI as `uri`, kept for backward compatibility.
    - `created` string, required: Creation timestamp, ISO 8601 with a `+hhmm` offset; `""` when none was recorded.
    - `lastChangeDate` string, nullable, required: Timestamp of the last data change in the bucket, ISO 8601 with a `+hhmm` offset.
    - `updated` string, nullable, required: Timestamp of the last bucket update, ISO 8601 with a `+hhmm` offset.
    - `isReadOnly` boolean, required: Whether the bucket is read-only (linked or external buckets).
    - `dataSizeBytes` integer, required: Total data size in bytes.
    - `rowsCount` integer, required: Total number of rows.
    - `isMaintenance` boolean, required: Whether the bucket is in maintenance mode.
    - `backend` string, required: Storage backend of the bucket: `snowflake`, `bigquery` or `postgres` (external buckets); older buckets may carry another backend name.
    - `sharing` 'organization' | 'organization-project' | 'specific-projects' | 'specific-users' | 'null', nullable, required: Sharing type of the bucket; `null` when the bucket is not shared.
    - `hasExternalSchema` boolean, required: Whether the bucket is an external (registered) bucket.
    - `databaseName` string, required: Database of a Snowflake external bucket or of a linked bucket's source; `""` otherwise.
    - `path` string, required: Dot-separated path of the bucket on the backend.
    - `isSnowflakeSharedDatabase` boolean, required: Whether the external bucket uses a Snowflake Secure Data Share.
    - `isLinkedBucket` boolean, required: Whether this bucket is linked from another project.
    - `color` string, nullable, required: CSS color of the bucket.
    - `bucketSharingAllowed` boolean, required: Whether the bucket can be shared.
    - `sharingParameters` union: Who the bucket is shared with. Present only when the bucket is shared; an empty array `[]` when it is shared with the organization or its projects.
      - object
        - `projects` object[]: Present when `sharing` is `specific-projects`.
          - `id` integer, required
          - `name` string, required
        - `users` object[]: Present when `sharing` is `specific-users`.
          - `id` integer, required
          - `name` string, required
          - `email` string, required
      - unknown[]
        - unknown
    - `sharedBy` object: Token that shared the bucket. Present only when the bucket is shared.
      - `id` integer, nullable, required
      - `name` string, nullable, required
      - `date` string, required: ISO 8601 with a `+hhmm` offset; `""` when none was recorded.
    - `sharedByActor` ActorResponse, required: Who performed the action and through which credential.
      - `type` 'token' | 'session' | 'pat' | 'system', required: Credential the action came through: a Storage token, a programmatic session, a personal access token, or system work.
      - `id` string, required: Token id as a string, session or personal access token UUID, or the system subject.
      - `name` string, required: Token description, the admin email for a session or personal access token, or the system label, as it was when the action happened.
      - `adminId` integer, nullable, required: Admin behind the credential; null for a token without an admin, for system work, and when the admin was not recorded (an object whose creator is known only from its token columns, including rows backfilled from them).
    - `owner` object, nullable, required: Bucket owner; `null` when no owner is set.
      - `id` integer, required
      - `name` string, required
      - `email` string, required
    - `sourceBucket` SharedBucketResponse: Shared bucket as seen from another project (also used as `sourceBucket` of a linked bucket).
      - `id` string, required: Bucket identifier in the source project.
      - `name` string, required: Bucket name.
      - `displayName` string, required: Bucket display name.
      - `stage` 'in' | 'out' | 'sys', required: Bucket stage.
      - `description` string, required: Bucket description.
      - `sharing` 'organization' | 'organization-project' | 'specific-projects' | 'specific-users' | 'null', nullable, required: Sharing type.
      - `created` string, required: Creation timestamp, ISO 8601 with a `+hhmm` offset; `""` when none was recorded.
      - `lastChangeDate` string, nullable, required: Timestamp of the last data change, ISO 8601 with a `+hhmm` offset.
      - `dataSizeBytes` integer, required
      - `rowsCount` integer, required
      - `backend` string, required: Storage backend of the bucket: `snowflake`, `bigquery` or `postgres` (external buckets); older buckets may carry another backend name.
      - `hasExternalSchema` boolean, required: Whether the bucket is an external (registered) bucket.
      - `databaseName` string, required: Database of a Snowflake external bucket or of a linked bucket's source; `""` otherwise.
      - `path` string, required: Dot-separated path of the bucket on the backend.
      - `project` object, required: Project owning the bucket.
        - `id` integer, required
        - `name` string, required
      - `color` string, nullable, required
      - `tables` object[]: Tables in the shared bucket (filtered aliases are omitted). Absent from a `sourceBucket` inside a table list or search with `include=bucketsWithoutSourceTables`.
        - `id` string, required
        - `name` string, required
        - `displayName` string, required
        - `path` string, required: Internal Storage path of the table (`/{bucket numeric id}-{table name}`); may be `""`.
      - `sharingParameters` union: Who the bucket is shared with. Present only when the bucket is shared; an empty array `[]` when it is shared with the organization or its projects.
        - object
          - `projects` object[]: Present when `sharing` is `specific-projects`.
            - `id` integer, required
            - `name` string, required
          - `users` object[]: Present when `sharing` is `specific-users`.
            - `id` integer, required
            - `name` string, required
            - `email` string, required
        - unknown[]
          - unknown
      - `sharedBy` object: Token that shared the bucket. Present only when the bucket is shared.
        - `id` integer, nullable, required
        - `name` string, nullable, required
        - `date` string, required: ISO 8601 with a `+hhmm` offset; `""` when none was recorded.
      - `sharedByActor` ActorResponse, required: Who performed the action and through which credential.
        - `type` 'token' | 'session' | 'pat' | 'system', required: Credential the action came through: a Storage token, a programmatic session, a personal access token, or system work.
        - `id` string, required: Token id as a string, session or personal access token UUID, or the system subject.
        - `name` string, required: Token description, the admin email for a session or personal access token, or the system label, as it was when the action happened.
        - `adminId` integer, nullable, required: Admin behind the credential; null for a token without an admin, for system work, and when the admin was not recorded (an object whose creator is known only from its token columns, including rows backfilled from them).
      - `owner` object, nullable, required: Bucket owner; `null` when no owner is set.
        - `id` integer, required
        - `name` string, required
        - `email` string, required
      - `metadata` MetadataItemResponse[]: Bucket metadata. Present only on the shared-buckets list with `include` containing `metadata`.
        - `id` string, required: Metadata record identifier
        - `key` string, required: Metadata key
        - `value` string, nullable, required: Metadata value
        - `provider` string, required: Id of the component that created the metadata
        - `timestamp` string, required: When the metadata was created or last updated, ISO 8601 with a `+hhmm` offset
    - `backendPath` string[], required: Full path of the bucket on the backend (e.g. database and schema).
    - `metadata` MetadataItemResponse[]: Bucket metadata records. Present only in the table detail and the synchronous table update.
      - `id` string, required: Metadata record identifier
      - `key` string, required: Metadata key
      - `value` string, nullable, required: Metadata value
      - `provider` string, required: Id of the component that created the metadata
      - `timestamp` string, required: When the metadata was created or last updated, ISO 8601 with a `+hhmm` offset
  - `metadata` MetadataItemResponse[]: Table metadata records. Present with `include=metadata`.
    - `id` string, required: Metadata record identifier
    - `key` string, required: Metadata key
    - `value` string, nullable, required: Metadata value
    - `provider` string, required: Id of the component that created the metadata
    - `timestamp` string, required: When the metadata was created or last updated, ISO 8601 with a `+hhmm` offset
  - `columnMetadata` TableColumnMetadataResponse: Column metadata of a table, keyed by column name. Built by Model_Row_MetadataTable::getTableColumnMetadataApiResponse().
  - `sourceTable` TableSourceTableResponse: Source table of an alias, extended with the metadata that propagates from the root source table for a simple alias with column auto-sync enabled.
    - `id` string, required: Source table ID
    - `uri` string, required: Source table URI
    - `project` object, required
      - `id` integer, required: Project ID
      - `name` string, required: Project name
    - `isAlias` boolean: Whether the source table is itself an alias
    - `metadata` MetadataItemResponse[]: Metadata of the root source table. Present only for an alias with column auto-sync, in the table detail or with `include=sourceMetadata`.
      - `id` string, required: Metadata record identifier
      - `key` string, required: Metadata key
      - `value` string, nullable, required: Metadata value
      - `provider` string, required: Id of the component that created the metadata
      - `timestamp` string, required: When the metadata was created or last updated, ISO 8601 with a `+hhmm` offset
    - `columnMetadata` union: Column metadata of the root source table, keyed by column name. Present only for an alias with column auto-sync, in the table detail or with `include=columnMetadata`/`include=sourceColumnMetadata`. An empty array `[]` in table lists when the source table has no column metadata.
      - TableColumnMetadataResponse: Column metadata of a table, keyed by column name. Built by Model_Row_MetadataTable::getTableColumnMetadataApiResponse().
      - unknown[]
        - unknown
    - `definition` TableDefinitionResponse: Native table definition, in the same shape as the create-table-from-definition endpoint. Built by Keboola\Connection\Storage\Service\Metadata\MetadataConvertor::createTableDefinitionResponseFromMetadata() for a typed table, or ::createUntypedTableDefinitionResponseFromMetadata() for an untyped one - for an untyped table, `basetype`, `canBeFiltered`, `distribution` and `index` are never present, and each column `definition` only ever carries `description`. A storage driver may add further backend-specific keys via its extendTableDefinitionResponse() hook, e.g. BigQuery adds `timePartitioning`, `clustering`, `rangePartitioning` and `requirePartitionFilter`. For an alias with auto-synced columns (including a linked-bucket table), column types come from the root source table and table and column descriptions are resolved along the alias chain, the alias's own value first.
      - `primaryKeysNames` string[], required: Primary key column names.
      - `columns` object[], required
        - `name` string, required: Column name.
        - `canBeFiltered` boolean: Whether the column type can be used in a `where` filter. Absent for an untyped table.
        - `definition` object, required: Column type definition. An empty object (`{}`) for an untyped column without a description.
          - `type` string: Backend-native column type. Absent for an untyped table.
          - `nullable` boolean: Whether the column accepts NULL. Absent for an untyped table.
          - `length` string, nullable: Backend-native type length/precision, for example `38,9`. Absent when not applicable.
          - `default` string, nullable: Default value of the column. Absent when not set.
          - `description` string: Column description.
        - `basetype` string, nullable: Keboola base type. Absent for an untyped table.
        - `policyTagState` 'protected' | 'unprotected' | 'unknown': Whether Keboola knows the column to be covered by a BigQuery policy tag, as of the last time the table was reflected. `protected` - a policy tag was observed on the column; `unprotected` - the table was observed and the column carried none; `unknown` - the table has never been observed, or the column carries protection Keboola cannot state (a tag on a field inside a STRUCT, or more than one tag). Present on BigQuery tables only, typed and untyped alike; absent on every other backend.
      - `description` string: Table description, when set.
      - `distribution` object: Present only when the table has a distribution type set. Absent for an untyped table.
        - `type` string, required
        - `distributionColumnsNames` string[], required
      - `index` object: Present only when the table has an index type set. Absent for an untyped table.
        - `type` string, required
        - `indexColumnsNames` string[], required
  - `aliasColumnsAutoSync` boolean: Present only for simple aliases.
  - `aliasFilter` AliasFilterResponse: Row filter of a filtered simple alias, as returned by Model_Row_MetadataTable::getAliasFilter().
    - `column` string, required: Filtered column name.
    - `operator` 'eq' | 'ne', required: Filter operator: `eq` (can be used with multiple values) or `ne`.
    - `values` string[], required: Values compared against the filtered column.
  - `selectSql` string: Present only for custom SQL aliases.
  - `isPersisted` boolean: Whether the alias is persisted as a table in the backend. Present only for alias tables.

## Other responses

- `400`: Invalid value in the include parameter.
- `403`: Access denied to the bucket.
- `404`: Bucket not found (`storage.buckets.notFound`).
- `503`: Bucket or its backend connection is under maintenance.

---

[API](https://skmtc.dev/keboola/apis/keboola-storage-api.md) - [All operations](https://skmtc.dev/keboola/apis/keboola-storage-api/llms.txt) - [OpenAPI document](https://skmtc.dev/keboola/apis/keboola-storage-api/revisions/34b5ceac0317?raw)