ClickHouse Snapshot API
The Snapshot API from ClickHouse — 3 operation(s) for snapshot.
Work with this as data
Every API here is available over the APIs.io API and to AI agents over MCP.
MCP server
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
Tools for apis
7 MCP tools reach this
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.
Call it yourself
curl for this page
This API
curl "https://apis.io/api/v1/apis/clickhouse:clickhouse-snapshot-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.
Get an API key
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
OpenAPI Specification
openapi: 3.2.0
info:
title: OpenAPI spec for ClickHouse Cloud Snapshot API
version: '1.0'
contact:
name: ClickHouse Support
url: https://clickhouse.com/docs/en/cloud/manage/openapi?referrer=openapi-1256081
email: support@clickhouse.com
servers:
- url: https://api.clickhouse.cloud
security:
- basicAuth: []
tags:
- name: Snapshot
paths:
/v1/organizations/{organizationId}/services/{serviceId}/snapshots:
get:
summary: List of service snapshots
description: '**This endpoint is in beta.** API contract is stable, and no breaking changes are expected in the future.
Returns a list of snapshots for the service, most recent first. Results are capped at `limit` (default 250) per page; the server may return fewer and caps the value at its own maximum. Every response carries `limit`, `totalCount` and `nextCursor`; pass `nextCursor` as the `cursor` query parameter to fetch the next page, repeating until it is null.'
operationId: snapshotGetList
parameters:
- in: path
name: organizationId
description: ID of the organization that owns the snapshot.
required: true
schema:
type: string
format: uuid
- in: path
name: serviceId
description: ID of the service the snapshot was created from.
required: true
schema:
type: string
format: uuid
- in: query
name: limit
description: Maximum number of results to return.
schema:
type: integer
minimum: 1
default: 250
- in: query
name: cursor
description: Opaque cursor from a previous response's `nextCursor`, marking where to resume the list.
schema:
type: string
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: object
properties:
status:
type: number
description: HTTP status code.
example: 200
requestId:
type: string
description: Unique id assigned to every request. UUIDv4
format: uuid
result:
type: array
items:
$ref: '#/components/schemas/Snapshot'
limit:
type: integer
description: Maximum number of results returned in this page.
totalCount:
type:
- integer
- 'null'
description: Total number of results across all pages. It has only informative value, thus is not guaranteed and it is provided on a best-effort basis. Null if the total count is unknown.
nextCursor:
type:
- string
- 'null'
description: Cursor for the next page, to be sent as the `cursor` query parameter. Null on the last page.
'400':
description: The request cannot be processed due to a client error. Please verify your request parameters and try again.
content:
application/json:
schema:
type: object
properties:
status:
type: number
description: HTTP status code.
example: 400
error:
type: string
description: Detailed error description.
requestId:
type: string
description: Unique id assigned to every request. UUIDv4
format: uuid
'500':
description: An internal server error has occurred. If this issue persists, please contact ClickHouse Cloud support for assistance.
content:
application/json:
schema:
type: object
properties:
status:
type: integer
description: HTTP status code.
example: 500
error:
type: string
description: Detailed error description.
requestId:
type: string
description: Unique id assigned to every request. UUIDv4
format: uuid
security:
- basicAuth:
- control-plane:service:view-snapshots
tags:
- Snapshot
x-badges:
- name: Beta
position: after
/v1/organizations/{organizationId}/services/{serviceId}/snapshots/{snapshotId}:
get:
summary: Get snapshot details
description: '**This endpoint is in beta.** API contract is stable, and no breaking changes are expected in the future.
Returns a single snapshot info.'
operationId: snapshotGet
parameters:
- in: path
name: organizationId
description: ID of the organization that owns the snapshot.
required: true
schema:
type: string
format: uuid
- in: path
name: serviceId
description: ID of the service the snapshot was created from.
required: true
schema:
type: string
format: uuid
- in: path
name: snapshotId
description: ID of the requested snapshot.
required: true
schema:
type: string
format: uuid
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: object
properties:
status:
type: number
description: HTTP status code.
example: 200
requestId:
type: string
description: Unique id assigned to every request. UUIDv4
format: uuid
result:
$ref: '#/components/schemas/Snapshot'
'400':
description: The request cannot be processed due to a client error. Please verify your request parameters and try again.
content:
application/json:
schema:
type: object
properties:
status:
type: number
description: HTTP status code.
example: 400
error:
type: string
description: Detailed error description.
requestId:
type: string
description: Unique id assigned to every request. UUIDv4
format: uuid
'500':
description: An internal server error has occurred. If this issue persists, please contact ClickHouse Cloud support for assistance.
content:
application/json:
schema:
type: object
properties:
status:
type: integer
description: HTTP status code.
example: 500
error:
type: string
description: Detailed error description.
requestId:
type: string
description: Unique id assigned to every request. UUIDv4
format: uuid
security:
- basicAuth:
- control-plane:service:view-snapshots
tags:
- Snapshot
x-badges:
- name: Beta
position: after
/v1/organizations/{organizationId}/services/{serviceId}/snapshotConfiguration:
get:
summary: Get service snapshot configuration
description: '**This endpoint is in beta.** API contract is stable, and no breaking changes are expected in the future.
Returns the service snapshot configuration.'
operationId: snapshotConfigurationGet
parameters:
- in: path
name: organizationId
description: ID of the organization that owns the service.
required: true
schema:
type: string
format: uuid
- in: path
name: serviceId
description: ID of the service.
required: true
schema:
type: string
format: uuid
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: object
properties:
status:
type: number
description: HTTP status code.
example: 200
requestId:
type: string
description: Unique id assigned to every request. UUIDv4
format: uuid
result:
$ref: '#/components/schemas/SnapshotConfiguration'
'400':
description: The request cannot be processed due to a client error. Please verify your request parameters and try again.
content:
application/json:
schema:
type: object
properties:
status:
type: number
description: HTTP status code.
example: 400
error:
type: string
description: Detailed error description.
requestId:
type: string
description: Unique id assigned to every request. UUIDv4
format: uuid
'500':
description: An internal server error has occurred. If this issue persists, please contact ClickHouse Cloud support for assistance.
content:
application/json:
schema:
type: object
properties:
status:
type: integer
description: HTTP status code.
example: 500
error:
type: string
description: Detailed error description.
requestId:
type: string
description: Unique id assigned to every request. UUIDv4
format: uuid
security:
- basicAuth:
- control-plane:service:view-snapshots
tags:
- Snapshot
x-badges:
- name: Beta
position: after
patch:
summary: Update service snapshot configuration
description: '**This endpoint is in beta.** API contract is stable, and no breaking changes are expected in the future.
Updates the service snapshot configuration. Requires ADMIN auth key role. Enables or disables scheduled snapshots and sets the cadence; when enabled, gap and timeFrame (in minutes) must together be one of the supported (gap, timeFrame) pairs: (30, 1440), (60, 2880). Provide at least one of enabled, gap, timeFrame; omit a field to leave it unchanged (null is not accepted). Enabling snapshots or changing the cadence requires an eligible organization (see the organization''s capabilities.snapshots).'
operationId: snapshotConfigurationUpdate
parameters:
- in: path
name: organizationId
description: ID of the organization that owns the service.
required: true
schema:
type: string
format: uuid
- in: path
name: serviceId
description: ID of the service.
required: true
schema:
type: string
format: uuid
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/SnapshotConfigurationPatchRequest'
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: object
properties:
status:
type: number
description: HTTP status code.
example: 200
requestId:
type: string
description: Unique id assigned to every request. UUIDv4
format: uuid
result:
$ref: '#/components/schemas/SnapshotConfiguration'
'400':
description: The request cannot be processed due to a client error. Please verify your request parameters and try again.
content:
application/json:
schema:
type: object
properties:
status:
type: number
description: HTTP status code.
example: 400
error:
type: string
description: Detailed error description.
requestId:
type: string
description: Unique id assigned to every request. UUIDv4
format: uuid
'500':
description: An internal server error has occurred. If this issue persists, please contact ClickHouse Cloud support for assistance.
content:
application/json:
schema:
type: object
properties:
status:
type: integer
description: HTTP status code.
example: 500
error:
type: string
description: Detailed error description.
requestId:
type: string
description: Unique id assigned to every request. UUIDv4
format: uuid
security:
- basicAuth:
- control-plane:service:manage-snapshots
tags:
- Snapshot
x-badges:
- name: Beta
position: after
components:
schemas:
Snapshot:
properties:
id:
description: Unique snapshot ID.
type: string
format: uuid
status:
description: 'Status of the snapshot: ''done'', ''error'', ''in_progress'', ''throttled''. ''throttled'' means snapshot creation was rate-limited and will be retried.'
type: string
enum:
- done
- error
- in_progress
- throttled
serviceId:
description: ID of the service the snapshot was created from.
type: string
startedAt:
description: Snapshot start timestamp. ISO-8601.
type: string
format: date-time
finishedAt:
description: Snapshot finish timestamp. ISO-8601. Available only for finished snapshots
type: string
format: date-time
sizeInBytes:
description: Size of the snapshot in bytes.
type: number
durationInSeconds:
description: Time in seconds it took to perform the snapshot. If the status is in_progress or throttled, this is the time in seconds since the snapshot started until now.
type: number
type:
description: Snapshot type. Always "full" — snapshots never chain off a parent.
type: string
enum:
- full
backupName:
description: Snapshot name on the external backup bucket.
type: string
bucket:
description: Backup bucket where the snapshot is stored.
oneOf:
- $ref: '#/components/schemas/AwsBackupBucketProperties'
- $ref: '#/components/schemas/GcpBackupBucketProperties'
- $ref: '#/components/schemas/AzureBackupBucketProperties'
AzureBackupBucketProperties:
properties:
bucketProvider:
description: Bucket provider
type: string
enum:
- AZURE
containerName:
description: Container Name
type: string
AwsBackupBucketProperties:
properties:
bucketProvider:
description: Bucket provider
type: string
enum:
- AWS
bucketPath:
description: Bucket path
type: string
iamRoleArn:
description: AWS IAM Role
type: string
iamRoleSessionName:
description: AWS IAM Role
type: string
iamRoleExternalId:
description: External ID the IAM role trust policy requires when the data plane assumes the role
type: string
GcpBackupBucketProperties:
properties:
bucketProvider:
description: Bucket provider
type: string
enum:
- GCP
bucketPath:
description: Bucket path
type: string
accessKeyId:
description: Access Key ID (HMAC key)
type: string
SnapshotConfiguration:
properties:
enabled:
description: Whether scheduled snapshots are enabled for the service.
type: boolean
gap:
description: Interval between snapshots, in minutes. Set together with timeFrame; only supported preset pairs are accepted.
type: number
timeFrame:
description: Retention window the snapshots cover, in minutes. Set together with gap; only supported preset pairs are accepted.
type: number
SnapshotConfigurationPatchRequest:
properties:
enabled:
description: Whether scheduled snapshots are enabled for the service.
type: boolean
gap:
description: Interval between snapshots, in minutes. Set together with timeFrame; only supported preset pairs are accepted.
type: number
timeFrame:
description: Retention window the snapshots cover, in minutes. Set together with gap; only supported preset pairs are accepted.
type: number
securitySchemes:
basicAuth:
type: http
scheme: basic
description: 'Use key ID and key secret obtained in ClickHouse Cloud console: https://clickhouse.com/docs/cloud/manage/openapi'
x-permission-scopes: The scope list of a `security` requirement holds ClickHouse Cloud API key permission ids (for example `control-plane:organization:view`), not OAuth scopes. OpenAPI has no field for API key permissions, so this is the closest available place. A key must hold every permission listed on an operation to call it; an operation with no scopes needs none beyond a valid key. Every operation declares at most one requirement object, always for this scheme, so the list is only ever conjunctive — alternative sets of permissions are never expressed.
x-tagGroups:
- name: Organization
tags:
- Organization
- Notifications
- Billing
- User management
- Role Management
- UDF
- name: Service
tags:
- Service
- Backup
- Snapshot
- Query API endpoints
- Saved queries
- name: API keys
tags:
- API keys
- name: Prometheus
tags:
- Prometheus
- name: ClickPipes
tags:
- ClickPipes
- name: ClickStack
tags:
- ClickStack
- name: Postgres
tags:
- Postgres