Create or replace service autoscaling schedule

POST/v1/organizations/{organizationId}/services/{serviceId}/scalingSchedule

Disclaimer: This beta endpoint is evolving; the API contract may change.

Creates or fully replaces the autoscaling schedule for a service. Pass an empty entries array to clear the schedule — a subsequent GET will return 404, and the response will contain an empty baseConfig (all fields absent). The base scaling config (applied when no entry is active) is managed separately via the replicaScaling endpoint. Requires the scheduled autoscaling feature to be enabled for the organization.

Authorizations

Authorizationstringheaderrequired
Use key ID and key secret obtained in ClickHouse Cloud console: https://clickhouse.com/docs/cloud/manage/openapi

Path parameters

organizationIdstringrequired
ID of the organization that owns the service.

format: uuid
serviceIdstringrequired
ID of the service.

format: uuid

Request bodyJSON

entriesarray ofobjectrequired
List of schedule entries. Pass an empty array to clear the schedule.
12 properties
- namestringrequired
  Human-readable label for this schedule entry.
  
  Example: "Business hours"
- weekdaysarray ofintegerrequired
  Days of the week this entry applies to. 0 = Sunday, 1 = Monday, …, 6 = Saturday.
  
  Example: [1,2,3,4,5]
- startHourUtcintegerrequired
  UTC hour (0–23) when this entry becomes active (inclusive).
  
  maximum: 23, minimum: 0
  Example: 9
- endHourUtcintegerrequired
  UTC hour (1–24) when this entry deactivates (exclusive). Must differ from startHourUtc. Set to 24 to end at midnight. Values less than startHourUtc create an overnight window spanning midnight.
  
  maximum: 24, minimum: 1
  Example: 17
- autoscalingModeoptionalverticalorhorizontal
  Autoscaling mode for this entry. "vertical" (the default when omitted) runs a fixed replica count while memory scales between minReplicaMemoryGb and maxReplicaMemoryGb; "horizontal" scales the replica count between minReplicas and maxReplicas at a fixed per-replica memory (minReplicaMemoryGb equal to maxReplicaMemoryGb). Horizontal requires the feature to be enabled for the organization.
  
  Example: "vertical"
- minReplicaMemoryGboptionalnumber
  Minimum memory per replica (Gb). Optional for vertical entries — provide both bounds for a memory range, or omit both to inherit memory from the base scaling config. Required for horizontal (both bounds, equal to maxReplicaMemoryGb — memory is fixed while the replica count scales). The upper bound is tier-dependent (lower for non-paid organizations) and enforced when the entry is applied.
  
  maximum: 356, minimum: 8
  Example: 16
- maxReplicaMemoryGboptionalnumber
  Maximum memory per replica (Gb). Optional for vertical entries — provide both bounds for a memory range, or omit both to inherit memory from the base scaling config. Required for horizontal (both bounds, equal to minReplicaMemoryGb — memory is fixed while the replica count scales). The upper bound is tier-dependent (lower for non-paid organizations) and enforced when the entry is applied.
  
  maximum: 356, minimum: 8
  Example: 16
- numReplicasoptionalinteger
  Fixed replica count for a vertical entry (autoscalingMode "vertical" or omitted). Mutually exclusive with minReplicas/maxReplicas. The per-service replica maximum is variable (tier-dependent, configurable per service) and enforced when the entry is applied, not at request time.
  
  minimum: 1
  Example: 3
- minReplicasoptionalinteger
  Minimum number of replicas. A minReplicas/maxReplicas band scales the replica count in a horizontal entry (autoscalingMode "horizontal"); when autoscalingMode is omitted or "vertical", an equal band (minReplicas === maxReplicas) is instead an accepted vertical fixed count and needs no horizontal entitlement. Must be provided together with maxReplicas. The per-service replica maximum is variable (tier-dependent, configurable per service) and enforced when the entry is applied, not at request time.
  
  minimum: 1
  Example: 2
- maxReplicasoptionalinteger
  Maximum number of replicas. A minReplicas/maxReplicas band scales the replica count in a horizontal entry (autoscalingMode "horizontal"); when autoscalingMode is omitted or "vertical", an equal band (minReplicas === maxReplicas) is instead an accepted vertical fixed count and needs no horizontal entitlement. Must be provided together with minReplicas. The per-service replica maximum is variable (tier-dependent, configurable per service) and enforced when the entry is applied, not at request time.
  
  minimum: 1
  Example: 3
- idleScalingoptionalboolean
  Whether idle scaling is enabled during this window.
- idleTimeoutMinutesoptionalinteger
  Idle timeout in minutes during this window.

Response

JSON

200

Successful response

JSON

statusoptionalnumber
HTTP status code.

Example: 200
requestIdoptionalstring
Unique id assigned to every request. UUIDv4

format: uuid
resultoptionalobject
3 properties
- entriesarray ofobjectrequired
  List of schedule entries.
  
  13 properties
  idstringrequired
  Unique identifier for this schedule entry.
  
  format: uuid
  namestringrequired
  Human-readable label for this schedule entry.
  
  weekdaysarray ofintegerrequired
  Days of the week this entry applies to. 0 = Sunday, 1 = Monday, …, 6 = Saturday.
  
  startHourUtcintegerrequired
  UTC hour (0–23) when this entry becomes active (inclusive).
  
  maximum: 23, minimum: 0
  endHourUtcintegerrequired
  UTC hour (1–24) when this entry deactivates (exclusive). Must differ from startHourUtc. Set to 24 to end at midnight. Values less than startHourUtc create an overnight window spanning midnight.
  
  maximum: 24, minimum: 1
  autoscalingModeverticalorhorizontalrequired
  Autoscaling mode for this entry. "vertical" runs a fixed replica count while memory scales; "horizontal" scales the replica count at a fixed per-replica memory. Defaults to "vertical" for entries persisted before the mode was exposed.
  
  isActiveNowbooleanrequired
  Whether this entry is currently active. Scheduled times are indicative — actions are applied on a best-effort basis and may be delayed by a few minutes.
  
  minReplicaMemoryGboptionalnumber
  Minimum memory per replica (Gb) during this window. A range in vertical; in horizontal it equals maxReplicaMemoryGb (memory is fixed while the replica count scales).
  
  maxReplicaMemoryGboptionalnumber
  Maximum memory per replica (Gb) during this window. A range in vertical; in horizontal it equals minReplicaMemoryGb (memory is fixed while the replica count scales).
  
  minReplicasoptionalinteger
  Minimum number of replicas during this window. For a horizontal entry the replica count scales between minReplicas and maxReplicas; for a vertical entry minReplicas and maxReplicas are equal and report the fixed replica count (both omitted when the entry stored no count).
  
  maxReplicasoptionalinteger
  Maximum number of replicas during this window. For a horizontal entry the replica count scales between minReplicas and maxReplicas; for a vertical entry minReplicas and maxReplicas are equal and report the fixed replica count (both omitted when the entry stored no count).
  
  idleScalingoptionalboolean
  Whether idle scaling is enabled during this window.
  
  idleTimeoutMinutesoptionalinteger
  Idle timeout in minutes during this window.
- baseConfigobjectrequired
  7 properties
  autoscalingModeoptionalverticalorhorizontal
  Autoscaling mode applied when no schedule entry is active. "vertical" runs a fixed replica count while memory scales; "horizontal" scales the replica count at a fixed per-replica memory.
  
  minReplicaMemoryGboptionalnumber
  Minimum memory per replica (Gb) when no schedule entry is active. Absent for services that do not autoscale memory.
  
  maxReplicaMemoryGboptionalnumber
  Maximum memory per replica (Gb) when no schedule entry is active. Absent for services that do not autoscale memory.
  
  minReplicasoptionalinteger
  Minimum number of replicas when no schedule entry is active.
  
  maxReplicasoptionalinteger
  Maximum number of replicas when no schedule entry is active.
  
  idleScalingoptionalboolean
  Whether idle scaling is enabled when no schedule entry is active.
  
  idleTimeoutMinutesoptionalinteger
  Idle timeout in minutes when no schedule entry is active.
- activeEntryIdoptionalstring
  ID of the currently-active schedule entry. Absent when no entry is active and the base config is in effect.
  
  format: uuid

Create or replace service autoscaling schedule

curl --request POST \
  --url https://api.clickhouse.cloud/v1/organizations/497f6eca-6276-4993-bfeb-53cbbbba6f08/services/497f6eca-6276-4993-bfeb-53cbbbba6f08/scalingSchedule \
  --header 'Authorization: Basic <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "entries": [
    {
      "name": "Business hours",
      "weekdays": [
        1,
        2,
        3,
        4,
        5
      ],
      "startHourUtc": 9,
      "endHourUtc": 17,
      "autoscalingMode": "vertical",
      "minReplicaMemoryGb": 16,
      "maxReplicaMemoryGb": 16,
      "numReplicas": 3,
      "minReplicas": 2,
      "maxReplicas": 3,
      "idleScaling": true,
      "idleTimeoutMinutes": 0
    }
  ]
}
'

const url = 'https://api.clickhouse.cloud/v1/organizations/497f6eca-6276-4993-bfeb-53cbbbba6f08/services/497f6eca-6276-4993-bfeb-53cbbbba6f08/scalingSchedule';
const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json', Authorization: 'Basic <token>'},
  body: JSON.stringify({
    entries: [
      {
        name: 'Business hours',
        weekdays: [1, 2, 3, 4, 5],
        startHourUtc: 9,
        endHourUtc: 17,
        autoscalingMode: 'vertical',
        minReplicaMemoryGb: 16,
        maxReplicaMemoryGb: 16,
        numReplicas: 3,
        minReplicas: 2,
        maxReplicas: 3,
        idleScaling: true,
        idleTimeoutMinutes: 0
      }
    ]
  })
};

fetch(url, options)
  .then(res => res.json())
  .then(json => console.log(json))
  .catch(err => console.error(err));

import requests

url = "https://api.clickhouse.cloud/v1/organizations/497f6eca-6276-4993-bfeb-53cbbbba6f08/services/497f6eca-6276-4993-bfeb-53cbbbba6f08/scalingSchedule"

payload = { "entries": [
        {
            "name": "Business hours",
            "weekdays": [1, 2, 3, 4, 5],
            "startHourUtc": 9,
            "endHourUtc": 17,
            "autoscalingMode": "vertical",
            "minReplicaMemoryGb": 16,
            "maxReplicaMemoryGb": 16,
            "numReplicas": 3,
            "minReplicas": 2,
            "maxReplicas": 3,
            "idleScaling": True,
            "idleTimeoutMinutes": 0
        }
    ] }
headers = {
    "Content-Type": "application/json",
    "Authorization": "Basic <token>"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

Response example

{
  "status": 200,
  "requestId": "d385ab22-0f51-4b97-9ecd-b8ff3fd4fcb6",
  "result": {
    "entries": [
      {
        "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
        "name": "string",
        "weekdays": [
          0
        ],
        "startHourUtc": 23,
        "endHourUtc": 1,
        "autoscalingMode": "vertical",
        "minReplicaMemoryGb": 0,
        "maxReplicaMemoryGb": 0,
        "minReplicas": 0,
        "maxReplicas": 0,
        "idleScaling": true,
        "idleTimeoutMinutes": 0,
        "isActiveNow": true
      }
    ],
    "baseConfig": {
      "autoscalingMode": "vertical",
      "minReplicaMemoryGb": 0,
      "maxReplicaMemoryGb": 0,
      "minReplicas": 0,
      "maxReplicas": 0,
      "idleScaling": true,
      "idleTimeoutMinutes": 0
    },
    "activeEntryId": "7fea8504-c822-495c-b273-d4283b184c89"
  }
}

{
  "status": 400,
  "error": "string",
  "requestId": "d385ab22-0f51-4b97-9ecd-b8ff3fd4fcb6"
}

{
  "status": 500,
  "error": "string",
  "requestId": "d385ab22-0f51-4b97-9ecd-b8ff3fd4fcb6"
}