> ## 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 Query API endpoints
> **Disclaimer:** This beta endpoint is evolving; the API contract may change.
Returns all active Query API endpoints for the service.
Beta
**Disclaimer:** This beta endpoint is evolving; the API contract may change.
Returns all active Query API endpoints for the service.
## OpenAPI
````yaml _specs/cloud-openapi.json GET /v1/organizations/{organizationId}/services/{serviceId}/query-api-endpoints
openapi: 3.1.2
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-1108755
email: support@clickhouse.com
servers:
- url: https://api.clickhouse.cloud
security:
- basicAuth: []
tags:
- name: Organization
- name: User management
- name: Billing
- name: Role Management
- name: Service
- name: Backup
- name: API keys
- name: Prometheus
- name: ClickPipes
- name: ClickStack
- name: Postgres
- name: UDF
- name: Query API endpoints
paths:
/v1/organizations/{organizationId}/services/{serviceId}/query-api-endpoints:
get:
tags:
- Query API endpoints
summary: List Query API endpoints
description: >-
**Disclaimer:** This beta endpoint is evolving; the API contract may
change.
Returns all active Query API endpoints for the
service.
operationId: queryApiEndpointList
parameters:
- in: path
name: organizationId
schema:
description: ID of the requested organization.
type: string
format: uuid
pattern: >-
^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000)$
required: true
description: ID of the requested organization.
- in: path
name: serviceId
schema:
description: ID of the requested service.
type: string
format: uuid
pattern: >-
^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000)$
required: true
description: ID of the requested service.
- in: query
name: cursor
schema:
description: Cursor returned in `pagination.nextCursor` from the previous page.
type: string
description: Cursor returned in `pagination.nextCursor` from the previous page.
- in: query
name: limit
schema:
description: >-
Maximum number of records to return per page. Defaults to 100.
Maximum is 100.
default: 100
type: integer
exclusiveMinimum: 0
maximum: 100
description: >-
Maximum number of records to return per page. Defaults to 100.
Maximum is 100.
responses:
'200':
description: Successful response.
content:
application/json:
schema:
type: object
properties:
status:
description: HTTP status code.
example: 200
type: integer
requestId:
description: Unique id assigned to every request. UUIDv4
type: string
format: uuid
pattern: >-
^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000)$
result:
$ref: '#/components/schemas/QueryApiEndpointListResponse'
required:
- status
- requestId
- result
additionalProperties: false
'400':
description: The request cannot be processed due to a client error.
content:
application/json:
schema:
type: object
properties:
error:
description: Human-readable error message.
type: string
status:
description: HTTP status code.
example: 400
type: integer
requestId:
description: Unique id assigned to every request. UUIDv4
type: string
format: uuid
pattern: >-
^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000)$
required:
- error
- status
- requestId
additionalProperties: false
'403':
description: The request is forbidden.
content:
application/json:
schema:
type: object
properties:
error:
description: Human-readable error message.
type: string
status:
description: HTTP status code.
example: 403
type: integer
requestId:
description: Unique id assigned to every request. UUIDv4
type: string
format: uuid
pattern: >-
^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000)$
required:
- error
- status
- requestId
additionalProperties: false
'404':
description: Service not found.
content:
application/json:
schema:
type: object
properties:
error:
description: Human-readable error message.
type: string
status:
description: HTTP status code.
example: 404
type: integer
requestId:
description: Unique id assigned to every request. UUIDv4
type: string
format: uuid
pattern: >-
^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000)$
required:
- error
- status
- requestId
additionalProperties: false
'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:
error:
description: Error message.
type: string
status:
type: integer
description: HTTP status code.
example: 500
requestId:
description: Unique id assigned to every request. UUIDv4
type: string
format: uuid
pattern: >-
^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000)$
required:
- error
- status
- requestId
additionalProperties: {}
components:
schemas:
QueryApiEndpointListResponse:
type: object
properties:
items:
description: >-
Active Query API endpoints for the service, including both owner
types.
type: array
items:
$ref: '#/components/schemas/PublicQueryApiEndpointListItem'
pagination:
$ref: '#/components/schemas/Pagination'
required:
- items
- pagination
additionalProperties: false
PublicQueryApiEndpointListItem:
type: object
properties:
id:
description: Unique ID of the Query API endpoint.
type: string
format: uuid
pattern: >-
^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000)$
name:
description: Name of the Query API endpoint.
type: string
database:
description: Database used by the Query API endpoint.
type: string
apiKeyIds:
description: API key IDs allowed to call the endpoint.
type: array
items:
type: string
format: uuid
pattern: >-
^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000)$
roles:
description: Database roles used by the endpoint.
type: array
items:
type: string
allowedOrigins:
description: Origins allowed by the endpoint CORS policy.
type: array
items:
type: string
url:
description: Public URL used to execute the endpoint.
example: >-
https://queries.clickhouse.cloud/run/00000000-0000-0000-0000-000000000000
type: string
format: uri
ownerType:
description: >-
Owner type of the Query API endpoint. Endpoints with a user owned
query cannot be updated or deleted through this API.
type: string
enum:
- user
- queryApiEndpoint
required:
- id
- name
- database
- apiKeyIds
- roles
- allowedOrigins
- url
- ownerType
additionalProperties: false
Pagination:
type: object
properties:
totalRecords:
description: Total number of records available.
type: integer
currentCursor:
description: Cursor for the current page. Null for the first page.
anyOf:
- type: string
- type: 'null'
nextCursor:
description: Cursor for the next page. Null if there are no more results.
anyOf:
- type: string
- type: 'null'
limit:
description: Maximum number of records returned per page.
type: integer
required:
- totalRecords
- currentCursor
- nextCursor
- limit
additionalProperties: false
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.
````