---
title: "List all buckets"
method: GET
path: "/v2/storage/buckets"
tags: ["Buckets"]
---

# List all buckets

`GET /v2/storage/buckets`

## Request

- Base URL: `https://connection.keboola.com`
- URL: `https://connection.keboola.com/v2/storage/buckets`
- 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/buckets/get.ts> (a function with typed inputs; its response is checked against the schema)

All buckets are returned.

[Buckets](https://help.keboola.com/storage/buckets/) are containers for one or more data tables. Access to buckets can be limited by access tokens. Each bucket has a *backend* in which all tables are created: Snowflake (default) or BigQuery.

## Query parameters

- `include` string

## Response `200`

List of buckets.

- BucketListItemResponse[]
  - `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); `[]` on backends without one.
  - `attributes` object[]: Deprecated, always an empty array. Present only when `include` is omitted or contains `attributes`.
  - `metadata` MetadataItemResponse[]: Bucket metadata. Present only when `include` contains `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
  - `linkedBy` object[]: Buckets in other projects linked to this bucket. Present only when `include` contains `linkedBuckets` and the bucket is linked somewhere.
    - `id` string: ID of the linked bucket in the target project.
    - `created` string: ISO 8601 with a `+hhmm` offset; `""` when none was recorded.
    - `project` object
      - `id` string
      - `name` string

---

[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)