---
title: "Create Table Snapshot"
method: POST
path: "/v2/storage/branch/{branchId}/tables/{id}/snapshots"
tags: ["Table Snapshotting"]
---

# Create Table Snapshot

`POST /v2/storage/branch/{branchId}/tables/{id}/snapshots`

## Request

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

**Snapshot creation is not supported for tables in external buckets.**

Creates a snapshot of the current state of the table. A table snapshot will contain:
- Table data,
- Table properties (primary key, etc.).

Snapshots of an alias table contain only alias settings, actual data are not stored with the snapshot.

Initial response returns job details [JobResponse](#model-JobResponse). The result of the asynchronous job can be fetched via `/v2/storage/jobs/{id}`. When the job completes, final result is [TableSnapshotCreateJobResult](#model-TableSnapshotCreateJobResult).

 Parameters of job will be [TableSnapshotCreateJobParams](#components-schemas-TableSnapshotCreateJobParams).

## Path parameters

- `id` string, required
- `branchId` string, required

## Headers

- `X-KBC-Backend` object
  - `context` string, nullable

## Request body

- CreateSnapshotRequest
  - `description` string, nullable: Snapshot description.

## Response `202`

Job accepted; returns job details.

- JobResponse: Response object for an asynchronous storage job.
  - `id` string, required: Job ID.
  - `status` string, required: Current status of the job.
  - `url` string, required: API detail URL for the job.
  - `tableId` string, nullable, required: ID of the table affected by the job.
  - `operationName` string, required: Type of operation performed.
  - `operationParams` object, required: Parameters for the operation.
  - `createdTime` string, date-time, required: Job creation timestamp.
  - `startTime` string, date-time, nullable, required: Job start timestamp.
  - `endTime` string, date-time, nullable, required: Job end timestamp.
  - `runId` string, nullable, required: Run ID for the job.
  - `results` union, required: Job results for the operation once it completes.
    - BucketForceUnlinkJobResult, nullable: The bucketForceUnlink job produces no results - the value is always null.
    - union: The result shape depends on the bucket backend.
      - object
        - `bucketId` string, required
        - `exposureName` string, required
        - `exposureDescription` string, nullable, required
        - `bigquery` object, required
          - `listingId` string, required
          - `subscribers` string[], required
      - object
        - `idBucket` integer, required: Identifier of the exposed bucket.
        - `backend` 'snowflake', required
        - `snowflake` object, required
          - `mode` 'grant' | 'share', required
          - `grantees` string[]: The stored grantee roles after the update. Present only in `grant` mode.
          - `accounts` string[]: The stored consumer accounts after the update. Present only in `share` mode.
          - `added` string[], required: All members granted by this job: the full new list is re-granted, so this is not a difference against the previous list. Empty when the request sent no member list.
          - `removed` string[], required: Members the job revoked access from: every member that may still have held access and is no longer listed, including members left by a failed earlier job.
    - BucketUpdateJobResult, nullable: The bucketUpdate job produces no results - the value is always null.
    - union: The result shape depends on the bucket backend.
      - object
        - `idBucket` integer, required: Identifier of the bucket the listing was created on.
        - `listingId` string, required: User-defined listing ID, unique within the project exchange.
        - `listingResourceName` string, required: Fully-qualified GCP Analytics Hub listing resource name.
        - `providerResourceName` string, required: Fully-qualified GCP Analytics Hub data exchange resource name.
      - object
        - `idBucket` integer, required: Identifier of the exposed bucket.
        - `backend` 'snowflake', required
        - `mode` 'grant' | 'share', required
        - `objectName` string, required: Quoted name of the exposed object: `"<DATABASE>"."<SCHEMA>"` in `grant` mode, the share name in `share` mode.
    - BucketListingDeleteResponse, nullable
      - `id` integer: Job ID.
      - `status` string: Job status.
      - `url` string: URL to retrieve job details.
      - `tableId` string, nullable: Table identifier if applicable.
      - `operationName` string: Name of the operation.
      - `operationParams` object: Parameters passed to the operation.
      - `createdTime` string, date-time: Job creation timestamp.
      - `startTime` string, date-time, nullable: Job start timestamp.
      - `endTime` string, date-time, nullable: Job completion timestamp.
      - `runId` string, nullable: Unique run identifier.
      - `results` object, nullable: Operation results; content varies.
      - `creatorToken` object: Creator token information.
        - `id` integer: ID of the token that created this job.
        - `description` string, nullable: Description of the creator token.
      - `metrics` object: Job execution metrics.
      - `error` object, nullable: Job error information if the job failed.
        - `code` string, nullable: Error code if job failed.
        - `message` string, nullable: Error message if job failed.
        - `exceptionId` string, nullable: Exception identifier.
    - BucketDeleteResponse, nullable
      - `id` integer: Job ID.
      - `status` string: Job status.
      - `url` string: URL to retrieve job details.
      - `tableId` string, nullable: Table identifier if applicable.
      - `operationName` string: Name of the operation.
      - `operationParams` object: Parameters passed to the operation.
      - `createdTime` string, date-time: Job creation timestamp.
      - `startTime` string, date-time, nullable: Job start timestamp.
      - `endTime` string, date-time, nullable: Job completion timestamp.
      - `runId` string, nullable: Unique run identifier.
      - `results` object, nullable: Operation results; content varies.
      - `creatorToken` object: Creator token information.
        - `id` integer: ID of the token that created this job.
        - `description` string, nullable: Description of the creator token.
      - `metrics` object: Job execution metrics.
      - `error` object, nullable: Job error information if the job failed.
        - `code` string, nullable: Error code if job failed.
        - `message` string, nullable: Error message if job failed.
        - `exceptionId` string, nullable: Exception identifier.
    - RefreshJobResponse
      - `uri` string, required
      - `id` string, required
      - `name` string, required
      - `displayName` string, required
      - `idBranch` integer, required
      - `stage` string, required
      - `description` string, required
      - `tables` string, required
      - `created` string, required
      - `lastChangeDate` string, nullable, required
      - `updated` string, nullable, required
      - `isReadOnly` boolean, required
      - `dataSizeBytes` integer, required
      - `rowsCount` integer, required
      - `isMaintenance` boolean, required
      - `backend` string, required
      - `sharing` string, nullable, required
      - `hasExternalSchema` boolean, required
      - `databaseName` string, required
      - `path` string, required
      - `isSnowflakeSharedDatabase` boolean, required
      - `color` string, nullable, required
      - `sharingParameters` object: Sharing parameters. Present only when the bucket is shared; `[]` when it is shared with the organization or its projects.
        - `projects` object[]: Present only when the sharing type is `specific-projects`.
          - `id` integer, required
          - `name` string, required
        - `users` object[]: Present only when the sharing type is `specific-users`.
          - `id` integer, required
          - `name` string, required
          - `email` string, required
      - `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
      - `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`.
              - …
            - `users` object[]: Present when `sharing` is `specific-users`.
              - …
          - 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
      - `warnings` object[], required: List of warnings related to the refresh operation.
        - `message` string, required
        - `context` string, nullable, required
    - BatchPurgeJobResult: Per-item outcome of a `componentConfigurationsBatchPurge` job. Present on both a successful job and a failed one — a failed job is one where at least one item is in `failed`, and the items in `purged` are permanently gone.
      - `purged` object[], required: Configurations that were permanently removed. This cannot be undone.
        - `componentId` string, required
        - `configurationId` string, required
      - `failed` object[], required: Configurations that were not purged, each with the reason. The one exception is `storage.components.configurations.batchPurgeItemFailed`, which says the purge did not finish and the configuration may or may not be gone — re-read the trash to find out.
        - `componentId` string, required
        - `configurationId` string, required
        - `error` object, required
          - `code` string, required: The string code the single-configuration purge would have returned, e.g. `storage.components.configurations.versionMismatch` when the item's `version` no longer matches. `storage.components.configurations.batchPurgeItemFailed` is the batch's own code for an item that failed outside the purge itself.
          - `message` string, required
    - BatchRestoreJobResult: Per-item outcome of a `componentConfigurationsBatchRestore` job. Present on both a successful job and a failed one — a failed job is one where at least one item is in `failed`.
      - `restored` object[], required: Configurations that are live again.
        - `componentId` string, required
        - `configurationId` string, required
        - `version` integer, required: Version the restore made. Restoring is a change, so this is one higher than the version the configuration had in the trash.
      - `failed` object[], required: Configurations that were not restored, each with the reason. The one exception is `storage.components.configurations.batchRestoreItemFailed`, which says the restore did not finish and the configuration may or may not be back — re-read the trash to find out.
        - `componentId` string, required
        - `configurationId` string, required
        - `error` object, required
          - `code` string, required: The string code the single-configuration restore would have returned, e.g. `storage.configuration.notFound`. `storage.components.configurations.batchRestoreItemFailed` is the batch's own code for an item that failed outside the restore itself.
          - `message` string, required
    - FileDeleteJobResult, nullable: The fileDelete job produces no results - the value is always null.
    - TableSnapshotCreateJobResult
      - `id` string, required
      - `description` string, nullable, required
      - `createdTime` string, date-time, required
      - `type` string, required
      - `creatorToken` object, required
        - `id` integer, required
        - `description` string, required
      - `actor` ActorResponse: 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).
      - `uri` string, required
      - `dataFileId` integer, required
    - TableDeleteJobResult: The deleteTable job produces no results - the value is always an empty array `[]`.
    - DeleteRowsJobResult: Result of the tableRowsDelete job.
    - TableExportAsyncJobResponse: Result of a finished table export job.
      - `file` object, required: Reference to the exported file in File Storage.
        - `id` integer, required
      - `cacheHit` boolean, required: Whether the export was served from a previously exported (cached) file.
    - PrimaryKeyCreateJobResult, nullable: The tablePrimaryKeyAdd job produces no results - the value is always null.
    - PrimaryKeyDeleteJobResult, nullable: The tablePrimaryKeyDelete job produces no results - the value is always null.
    - TableRestoreResult
      - `tableId` string, required: ID of the restored table.
      - `mode` 'undrop' | 'undropAs' | 'pointInTime', required
      - `warnings` string[], required: What the restore could not bring back, e.g. aliases removed together with the table.
    - TableSwapResult
      - `tableAStringId` string, required: String id of the source table.
      - `tableBStringId` string, required: String id of the target table.
    - TableCreateResponse
      - `uri` string, required: Table API URI
      - `id` string, required: Table ID
      - `name` string, required: Table name
      - `displayName` string, required: Table display name
      - `transactional` boolean, required: Is transactional
      - `primaryKey` string[], required: Primary key columns
      - `indexType` string, nullable, required: Index type
      - `indexKey` string[], required: Index key columns
      - `distributionType` string, nullable, required: Distribution type
      - `distributionKey` string[], required: Distribution key columns
      - `syntheticPrimaryKeyEnabled` boolean, required: Synthetic primary key enabled
      - `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: Rows count
      - `dataSizeBytes` integer, nullable, required: Data size in bytes
      - `isAlias` boolean, required: Is alias
      - `isAliasable` boolean, required: Is aliasable
      - `isTyped` boolean, required: Is typed table
      - `isDescriptionSystemManaged` boolean, required: Whether the description is managed by the system
      - `timestampType` 'MANAGED' | 'SELFMANAGED' | 'NONE', required: How the `_timestamp` column is managed
      - `tableType` string, required: Table type
      - `path` string, required: Table path
      - `columns` string[], required: List of column names.
      - `sourceTable` SourceTableResponse
        - `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
      - `aliasColumnsAutoSync` boolean: Alias columns auto sync. 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: Custom SQL of the alias. Present only for custom SQL aliases.
      - `isPersisted` boolean: Whether the alias is persisted as a table in the backend. Present only for aliases.
    - TableUpdateJobResult, nullable: The tableUpdate job produces no results - the value is always null.
    - ColumnCreateJobResult, nullable: The tableColumnAdd job produces no results - the value is always null.
    - ColumnDeleteJobResult, nullable: The tableColumnDelete job produces no results - the value is always null.
    - TableExportJobResponse
      - `file` object, required
        - `id` integer, required
  - `creatorToken` object, required: Storage token the job runs as. Use `actor` to learn who created the job.
    - `id` string, nullable, required: Access token ID as a string, kept for compatibility. Null for a job that runs without a token row.
    - `description` string, nullable, required: Access token description.
  - `actor` 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).
  - `metrics` object, required: Job metrics.
    - `inCompressed` boolean, required: Input is compressed.
    - `inBytes` integer, required: Input bytes.
    - `inBytesUncompressed` integer, required: Input bytes uncompressed.
    - `outCompressed` boolean, required: Output is compressed.
    - `outBytes` integer, required: Output bytes.
    - `outBytesUncompressed` integer, required: Output bytes uncompressed.
  - `error` object: Error details. Present only when the job failed.
    - `code` string, required: Error code.
    - `message` string, required: Error message.
    - `exceptionId` string, required: Exception identifier.
    - `contextParams` object, nullable, required: Context parameters for the error.
    - `uuid` string, nullable, required: Error UUID.

## Other responses

- `400`: Snapshots are not supported for tables in external buckets (`storage.buckets.snapshotNotSupported`) or by the backend (`storage.driver.unsupportedOperation`).
- `403`: Access denied.
- `404`: The table was not found (`storage.tables.notFound`).
- `503`: Bucket or backend 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)