openapi: 3.2.0 info: title: OpenAPI spec for ClickHouse Cloud Billing API version: '1.0' contact: name: ClickHouse Support url: https://clickhouse.com/docs/en/cloud/manage/openapi?referrer=openapi-1107336 email: support@clickhouse.com servers: - url: https://api.clickhouse.cloud security: - basicAuth: [] tags: - name: Billing paths: /v1/organizations/{organizationId}/usageCost: get: summary: Get organization usage costs description: Returns a grand total and a list of daily, per-entity organization usage cost records for the organization in the queried time period (maximum 31 days). All days in both the request and the response are evaluated based on the UTC timezone. operationId: usageCostGet parameters: - in: path name: organizationId description: ID of the requested organization. required: true schema: type: string format: uuid - in: query name: from_date description: Start date for the report, e.g. 2024-12-19. schema: type: string format: date required: true - in: query name: to_date description: End date (inclusive) for the report, e.g. 2024-12-20. This date cannot be more than 30 days after from_date (for a maximum queried period of 31 days). schema: type: string format: date required: true - in: query name: filter description: Filter criteria to apply when retrieving the usage cost report. Currently, only filtering by resource tags is supported. schema: type: array items: type: string example: - tag:Environment=Production - tag:Department=Engineering - tag:isActive 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/UsageCost' '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 tags: - Billing /v1/organizations/{organizationId}/activeBalances: get: summary: Get organization active prepaid balances description: 'DEPRECATED. Use the `/v1/organizations/{organizationId}/creditBalances` endpoint instead. Returns the active prepaid credit balances for the organization, each with its own balance ID and remaining credits, along with the total remaining credits across all active balances. A balance is active when it has started, has not expired, and has credits remaining. Balances are ordered by expiration date, soonest first, and the returned page is capped at `limit` (default and maximum 100). When `totalCount` exceeds the number of returned balances, page with `limit`/`offset` to retrieve them all. `totalRemainingPrepaidCredits` always covers every active balance, not just the returned page.' operationId: activeBalancesGet parameters: - in: path name: organizationId description: ID of the requested organization. required: true schema: type: string format: uuid - in: query name: limit description: Maximum number of results to return. schema: type: integer minimum: 1 maximum: 100 default: 100 - in: query name: offset description: Number of results to skip before returning. schema: type: integer minimum: 0 default: 0 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/ActiveBalances' '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 deprecated: true tags: - Billing /v1/organizations/{organizationId}/creditBalances: get: summary: Get organization active credit balances description: '**Disclaimer:** This beta endpoint is evolving; the API contract may change. Returns the active credit balances for the organization, each with its own balance ID, type and remaining credits, along with the total remaining credits across all of them. A balance is active when it has started, has not expired, and has credits remaining. Balances are ordered by expiration date, soonest first. The list is always present and is empty when the organization has no active balances.' operationId: creditBalancesGet parameters: - in: path name: organizationId description: ID of the requested organization. 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/CreditBalances' '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 tags: - Billing x-badges: - name: Beta position: after components: schemas: ActiveBalance: properties: id: description: Unique ID of the prepaid balance. type: string format: uuid remainingPrepaidCredits: description: Remaining credits available on this balance, in ClickHouse Credits (CHCs). type: number totalAmount: description: Total credits granted on this balance, in ClickHouse Credits (CHCs). type: number amountSpent: description: Credits spent from this balance, in ClickHouse Credits (CHCs). type: number startDate: description: Date the balance became active. ISO-8601, based on the UTC timezone. type: string format: date-time expirationDate: description: Date the balance expires. ISO-8601, based on the UTC timezone. type: string format: date-time UsageCost: properties: grandTotalCHC: description: Grand total cost of usage in ClickHouse Credits (CHCs). type: number costs: type: array description: List of daily, per-entity usage cost records. items: $ref: '#/components/schemas/UsageCostRecord' CreditBalances: properties: totalRemainingCredits: description: Total remaining credits across all active balances, in ClickHouse Credits (CHCs). type: number balances: type: array description: List of active balances for the organization. Empty when the organization has none. items: $ref: '#/components/schemas/CreditBalance' ActiveBalances: properties: totalRemainingPrepaidCredits: description: Total remaining credits across all active prepaid balances, in ClickHouse Credits (CHCs). type: number prepaidBalances: type: array description: List of active prepaid balances for the organization. items: $ref: '#/components/schemas/ActiveBalance' CreditBalance: properties: id: description: Unique ID of the balance. type: string format: uuid type: description: Type of the balance. type: string enum: - prepaid - trial remainingCredits: description: Remaining credits available on this balance, in ClickHouse Credits (CHCs). type: number totalAmount: description: Total credits granted on this balance, in ClickHouse Credits (CHCs). type: number amountSpent: description: Credits spent from this balance, in ClickHouse Credits (CHCs). type: number startDate: description: Date the balance became active. ISO-8601, based on the UTC timezone. type: string format: date-time expirationDate: description: Date the balance expires. ISO-8601, based on the UTC timezone. type: string format: date-time UsageCostMetrics: properties: storageCHC: description: Cost of storage in ClickHouse Credits (CHCs). Applies to dataWarehouse entities. type: number backupCHC: description: Cost of backup in ClickHouse Credits (CHCs). Applies to dataWarehouse entities. type: number computeCHC: description: Cost of compute in ClickHouse Credits (CHCs). Applies to service and clickpipe entities. type: number dataTransferCHC: description: Cost of data transfer in ClickHouse Credits (CHCs). Applies to clickpipe entities. type: number initialLoadCHC: description: Cost of initial load and resyncs in ClickHouse Credits (CHCs). Applies to clickpipe entities. type: number publicDataTransferCHC: description: Cost of data transfer in ClickHouse Credits (CHCs). Applies to service entities. type: number interRegionTier1DataTransferCHC: description: Cost of tier1 inter-region data transfer in ClickHouse Credits (CHCs). Applies to service entities. type: number interRegionTier2DataTransferCHC: description: Cost of tier2 inter-region data transfer in ClickHouse Credits (CHCs). Applies to service entities. type: number interRegionTier3DataTransferCHC: description: Cost of tier3 inter-region data transfer in ClickHouse Credits (CHCs). Applies to service entities. type: number interRegionTier4DataTransferCHC: description: Cost of tier4 inter-region data transfer in ClickHouse Credits (CHCs). Applies to service entities. type: number UsageCostRecord: properties: dataWarehouseId: description: ID of the dataWarehouse this entity belongs to (or is). type: string format: uuid serviceId: description: ID of the service this entity belongs to (or is). Set to null for dataWarehouse entities. type: - string - 'null' format: uuid date: description: Date of the usage. ISO-8601 date, based on the UTC timezone. type: string format: date entityType: description: Type of the entity. type: string enum: - datawarehouse - service - clickpipe entityId: description: Unique ID of the entity. type: string format: uuid entityName: description: Name of the entity. type: string metrics: $ref: '#/components/schemas/UsageCostMetrics' totalCHC: description: Total cost of usage in ClickHouse Credits (CHCs) for this entity. type: number locked: description: When true, the record is immutable. Unlocked records are subject to change until locked. type: boolean 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-tagGroups: - name: Organization tags: - Organization - Billing - User management - Role Management - UDF - name: Service tags: - Service - Backup - name: API keys tags: - API keys - name: Prometheus tags: - Prometheus - name: ClickPipes tags: - ClickPipes - name: ClickStack tags: - ClickStack - name: Postgres tags: - Postgres