---
title: "Search Tables"
method: GET
path: "/v2/storage/search/tables"
tags: ["Search"]
---

# Search Tables

`GET /v2/storage/search/tables`

## Request

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

Search all tables accessible by the token by either metadataKey, metadataValue or metadataProvider. By default, all tables are returned with their attributes and information about the containing bucket. At least one of parameters metadataKey|metadataValue|metadataProvider must be provided.

The `include` parameter is a comma separated list of resources to include for each table: `buckets`, `columns`, `metadata`, `columnMetadata`, `sourceMetadata` (for alias tables, includes source table metadata in `sourceTable.metadata`; works across projects for linked buckets), `sourceColumnMetadata` (for alias tables, includes source column metadata in `sourceTable.columnMetadata`).

## Query parameters

- `metadataKey` string, nullable: Metadata key to search for.
- `metadataValue` string, nullable: Metadata value to search for.
- `metadataProvider` string, nullable: Metadata provider to search for.
- `include` union: Resources to include for each table: buckets, columns, metadata, columnMetadata, sourceMetadata, sourceColumnMetadata. Accepts a comma-separated string or a repeated array. Default: attributes,buckets.
  - string: Comma-separated list of resources.
  - string[]: Repeated array of resources.

## Response `200`

List of tables matching the search criteria.

- SearchTablesResponse[]
  - `uri` string, required
  - `id` string, required
  - `name` string, required
  - `displayName` string, required
  - `transactional` boolean, required
  - `primaryKey` string[], required
  - `indexType` string, nullable, required
  - `indexKey` string[], required
  - `distributionType` string, nullable, required
  - `distributionKey` string[], required
  - `syntheticPrimaryKeyEnabled` boolean, required
  - `created` string, nullable, required: Creation timestamp, ISO 8601 with a `+hhmm` offset; `null` for a zero date.
  - `lastImportDate` string, nullable, required: Last import timestamp, ISO 8601 with a `+hhmm` offset.
  - `lastChangeDate` string, nullable, required: Last change timestamp, 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
  - `timestampType` string, required
  - `tableType` string, required
  - `path` string, required
  - `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 (non-SQL) alias tables.
  - `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.
  - `attributes` object[]: Deprecated, always empty. Present with `include=attributes` (default).
  - `columns` string[]: 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. 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().

## Other responses

- `400`: Returned when none of metadataKey, metadataValue, metadataProvider is provided.

---

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