> ## Documentation Index
> Fetch the complete documentation index at: https://clickhouse.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# List of service snapshots
> **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.
Beta
**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.
#### Permission
The API key must have the `control-plane:service:view-snapshots` permission.
## OpenAPI
````yaml _specs/cloud-openapi.json GET /v1/organizations/{organizationId}/services/{serviceId}/snapshots
openapi: 3.1.1
info:
title: OpenAPI spec for ClickHouse Cloud
version: '1.0'
contact:
name: ClickHouse Support
url: >-
https://clickhouse.com/docs/en/cloud/manage/openapi?referrer=openapi-1312017
email: support@clickhouse.com
servers:
- url: https://api.clickhouse.cloud
security:
- basicAuth: []
tags:
- name: Organization
- name: Notifications
- name: User management
- name: Billing
- name: Role Management
- name: Service
- name: Backup
- name: Snapshot
- name: API keys
- name: Prometheus
- name: ClickPipes
- name: ClickStack
- name: Postgres
- name: UDF
- name: Query API endpoints
- name: Saved queries
paths:
/v1/organizations/{organizationId}/services/{serviceId}/snapshots:
get:
tags:
- Snapshot
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
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'
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
AzureBackupBucketProperties:
properties:
bucketProvider:
description: Bucket provider
type: string
enum:
- AZURE
containerName:
description: Container Name
type: string
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.
````