Skip to content
ClickHouse Docs
ClickHouse DocsClickHouse Docs
49.6kGet Started

Update service auto scaling settings

View as MarkdownEdit this pageReport an issueSet up docs MCP
PATCH/v1/organizations/{organizationId}/services/{serviceId}/replicaScaling

Updates minimum and maximum memory limits per replica and idle mode scaling behavior for the service. Supports both vertical autoscaling (fixed replica count, variable memory) and horizontal autoscaling (variable replica count, fixed memory). The memory settings are available only for "production" services and must be a multiple of 4 starting from 8GB. For vertical autoscaling, please contact support to enable adjustment of numReplicas. For horizontal autoscaling (autoscalingMode "horizontal" with minReplicas/maxReplicas), contact support to enable the feature for your organization.

Authorizations

Path parameters

  • organizationIdstringrequired

    ID of the organization that owns the service.

    format: uuid
  • serviceIdstringrequired

    ID of the service to update scaling parameters.

    format: uuid

Request bodyJSON

  • minReplicaMemoryGboptionalnumber

    Minimum auto-scaling memory in Gb for a single replica. Available only for 'production' services. Must be a multiple of 4 and greater than or equal to 8. A range in vertical autoscaling; equal to maxReplicaMemoryGb in horizontal.

    maximum: 356, minimum: 8
    Example: 16
  • maxReplicaMemoryGboptionalnumber

    Maximum auto-scaling memory in Gb for a single replica. Available only for 'production' services. Must be a multiple of 4 and lower than or equal to 120 for non paid services or 356 for paid services. A range in vertical autoscaling; equal to minReplicaMemoryGb in horizontal.

    maximum: 356, minimum: 8
    Example: 120
  • autoscalingModeoptionalverticalorhorizontal

    Target autoscaling mode. Omit to keep the service on its current mode. "vertical" 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). Switching to horizontal requires the feature to be enabled for the organization.

    Example: "vertical"
  • numReplicasoptionalinteger

    Fixed replica count for vertical autoscaling (autoscalingMode "vertical"). Mutually exclusive with minReplicas/maxReplicas. When switching to vertical (autoscalingMode "vertical") with numReplicas and no memory, the service's stored baseline per-replica memory is kept as the new vertical range. Please contact support to enable adjustment of numReplicas.

    maximum: 20, minimum: 1
    Example: 3
  • minReplicasoptionalinteger

    Minimum number of replicas. A minReplicas/maxReplicas band scales the replica count in horizontal autoscaling (autoscalingMode "horizontal"). Must be provided together with maxReplicas. Mutually exclusive with numReplicas. Requires horizontal autoscaling to be enabled for the service, unless autoscalingMode is omitted or "vertical" and minReplicas equals maxReplicas (an equal band is then an accepted vertical fixed count and needs no horizontal entitlement).

    maximum: 20, minimum: 1
    Example: 1
  • maxReplicasoptionalinteger

    Maximum number of replicas. A minReplicas/maxReplicas band scales the replica count in horizontal autoscaling (autoscalingMode "horizontal"). Must be provided together with minReplicas. Mutually exclusive with numReplicas. Requires horizontal autoscaling to be enabled for the service, unless autoscalingMode is omitted or "vertical" and minReplicas equals maxReplicas (an equal band is then an accepted vertical fixed count and needs no horizontal entitlement).

    maximum: 20, minimum: 1
    Example: 5
  • idleScalingoptionalboolean

    When set to true the service is allowed to scale down to zero when idle. True by default.

  • idleTimeoutMinutesoptionalnumber

    Set minimum idling timeout (in minutes). Must be >= 5 minutes.

Response

JSON

200

Successful response

JSON
  • statusoptionalnumber

    HTTP status code.

    Example: 200
  • requestIdoptionalstring

    Unique id assigned to every request. UUIDv4

    format: uuid
  • resultoptionalobject
    40 properties
    • autoscalingModeverticalorhorizontalrequired

      Configured autoscaling mode. "vertical" 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. This is the baseline configuration; the mode currently applied (which may differ while a schedule entry is active) is currentScaling.effectiveAutoscalingMode.

      Example: "vertical"
    • currentScalingobjectrequired
      8 properties
      • effectiveAutoscalingModeoptionalverticalorhorizontal

        Autoscaling mode currently in effect on the running service. May diverge from the configured baseline mode while a schedule entry is active.

      • effectiveMinReplicaMemoryGboptionalnumber

        Minimum memory per replica (Gb) currently applied to the running service. May diverge from the top-level minReplicaMemoryGb baseline while a schedule entry is active.

      • effectiveMaxReplicaMemoryGboptionalnumber

        Maximum memory per replica (Gb) currently applied to the running service. May diverge from the top-level maxReplicaMemoryGb baseline while a schedule entry is active. Reflects the stored value: normally equal to effectiveMinReplicaMemoryGb in horizontal mode, but a legacy service stored with an unequal memory range reports the stored bounds as-is.

      • effectiveMinReplicasoptionalinteger

        Minimum number of replicas currently applied to the running service. May diverge from the baseline while a schedule entry is active. Reflects the stored value: normally equal to effectiveMaxReplicas in vertical mode (a fixed replica count), but a legacy service stored with an unequal replica range reports the stored bounds as-is.

      • effectiveMaxReplicasoptionalinteger

        Maximum number of replicas currently applied to the running service. May diverge from the baseline while a schedule entry is active.

      • effectiveIdleScalingoptionalboolean

        Whether idle scaling is currently in effect on the service. May diverge from the top-level idleScaling baseline while a schedule entry is active.

      • effectiveIdleTimeoutMinutesoptionalinteger

        Idle timeout in minutes currently in effect on the service. May diverge from the top-level idleTimeoutMinutes baseline while a schedule entry is active.

      • activeEntryIdoptionalstring

        ID of the schedule entry whose values are currently applied to the service. Absent when no entry is active.

        format: uuid
    • idoptionalstring

      Unique service ID.

      format: uuid
    • nameoptionalstring

      Name of the service. Alphanumerical string with whitespaces up to 50 characters.

      maxLength: 50, minLength: 1
    • provideroptionalawsorgcporazure

      Cloud provider

    • regionoptionalap-northeast-1orap-northeast-2orap-south-1orap-southeast-1orap-southeast-2orca-central-1+18 more

      Service region.

    • stateoptionalstartingorstoppingorterminatingorsoftdeletingorawakingorpartially_running+8 more

      Current state of the service.

    • clickhouseVersionoptionalstring

      ClickHouse version of the service.

    • endpointsoptionalarray ofobject

      List of all service endpoints.

      4 properties
      • protocoloptionalhttpsornativesecureormysql

        Endpoint protocol: 'https', 'nativesecure', 'mysql'.

        Example: "mysql"
      • hostoptionalstring

        Service host name

      • portoptionalnumber

        Numeric port

      • usernameoptionalstring | null

        Optional username for the endpoint

    • tierdeprecateddevelopmentorproductionordedicated_high_memordedicated_high_cpuordedicated_standardordedicated_standard_n2d_standard_4+5 more

      DEPRECATED for BASIC, SCALE and ENTERPRISE organization tiers. Use minReplicaMemoryGb, maxReplicaMemoryGb, and numReplicas instead. Tier of the service: 'development', 'production', 'dedicated_high_mem', 'dedicated_high_cpu', 'dedicated_standard', 'dedicated_standard_n2d_standard_4', 'dedicated_standard_n2d_standard_8', 'dedicated_standard_n2d_standard_32', 'dedicated_standard_n2d_standard_128', 'dedicated_standard_n2d_standard_32_16SSD', 'dedicated_standard_n2d_standard_64_24SSD'. Production services scale, Development are fixed size. Azure services don't support Development tier

    • minTotalMemoryGbdeprecatednumber

      DEPRECATED - inaccurate for services with non-default numbers of replicas. Use minReplicaMemoryGb instead. Minimum memory of three workers during auto-scaling in Gb. Available only for 'production' services. Must be a multiple of 12 and greater than or equal to 24. Always absent for horizontal-autoscaling services (replica count is variable).

      maximum: 1068, minimum: 24
      Example: 48
    • maxTotalMemoryGbdeprecatednumber

      DEPRECATED - inaccurate for services with non-default numbers of replicas. Use maxReplicaMemoryGb instead. Maximum memory of three workers during auto-scaling in Gb. Available only for 'production' services. Must be a multiple of 12 and lower than or equal to 360 for non paid services or 1068 for paid services. Always absent for horizontal-autoscaling services (replica count is variable).

      maximum: 1068, minimum: 24
      Example: 360
    • minReplicaMemoryGboptionalnumber

      Minimum auto-scaling memory in Gb for a single replica. Available only for 'production' services. Must be a multiple of 4 and greater than or equal to 8. A range in vertical autoscaling; equal to maxReplicaMemoryGb in horizontal (memory is fixed while the replica count scales).

      maximum: 356, minimum: 8
      Example: 16
    • maxReplicaMemoryGboptionalnumber

      Maximum auto-scaling memory in Gb for a single replica. Available only for 'production' services. Must be a multiple of 4 and lower than or equal to 120 for non paid services or 356 for paid services. A range in vertical autoscaling; equal to minReplicaMemoryGb in horizontal (memory is fixed while the replica count scales).

      maximum: 356, minimum: 8
      Example: 120
    • numReplicasoptionalinteger

      Number of replicas for the service. The number of replicas must be between 2 and 20 for the first service in a warehouse. Services that are created in an existing warehouse can have a number of replicas as low as 1. Further restrictions may apply based on your organization's tier. It defaults to 1 for the BASIC tier and 3 for the SCALE and ENTERPRISE tiers. Present only when the service uses vertical autoscaling. For horizontal autoscaling, use minReplicas and maxReplicas instead.

      maximum: 20, minimum: 1
      Example: 3
    • minReplicasoptionalinteger

      Minimum number of replicas for horizontal autoscaling. Present only when the service uses horizontal autoscaling.

      maximum: 20, minimum: 1
      Example: 1
    • maxReplicasoptionalinteger

      Maximum number of replicas for horizontal autoscaling. Present only when the service uses horizontal autoscaling.

      maximum: 20, minimum: 1
      Example: 5
    • replicaMemoryGboptionalnumber

      Fixed memory per replica in Gb for horizontal autoscaling. Present only when the service uses horizontal autoscaling. Must be a multiple of 4, at least 8 Gb, and at most 120 Gb for non paid services or 356 Gb for paid services.

      maximum: 356, minimum: 8
      Example: 32
    • idleScalingoptionalboolean

      When set to true the service is allowed to scale down to zero when idle. True by default.

    • idleTimeoutMinutesoptionalnumber

      Set minimum idling timeout (in minutes). Must be >= 5 minutes.

    • ipAccessListoptionalarray ofobject

      List of IP addresses allowed to access the service

      2 properties
      • sourceoptionalstring

        IP or CIDR

      • descriptionoptionalstring

        Optional description of IPv4 address or IPv4 CIDR to allow access from

    • createdAtoptionalstring

      Service creation timestamp. ISO-8601.

      format: date-time
    • encryptionKeyoptionalstring

      Optional customer provided disk encryption key

    • encryptionAssumedRoleIdentifieroptionalstring

      Optional role to use for disk encryption

    • iamRoleoptionalstring

      IAM role used for accessing objects in s3

    • privateEndpointIdsoptionalarray ofstring

      List of private endpoints

    • availablePrivateEndpointIdsoptionalarray ofstring

      List of available private endpoints ids that can be attached to the service

    • dataWarehouseIdoptionalstring

      Data warehouse containing this service

    • isPrimaryoptionalboolean

      True if this service is the primary service in the data warehouse

    • isReadonlyoptionalboolean

      True if this service is read-only. It can only be read-only if a dataWarehouseId is provided.

    • releaseChanneloptionalslowordefaultorfast

      Select fast if you want to get new ClickHouse releases as soon as they are available. You'll get new features faster, but with a higher risk of bugs. Select slow if you would like to defer releases to give yourself more time to test. This feature is only available for production services. default is the regular release channel.

    • byocIdoptionalstring

      This is the ID returned after setting up a region for Bring Your Own Cloud (BYOC). When the byocId parameter is specified, the minReplicaMemoryGb and the maxReplicaGb parameters are required too, with values included among the following sizes: 48, 116, 172, 232.

    • hasTransparentDataEncryptionoptionalboolean

      True if the service should have the Transparent Data Encryption (TDE) enabled. TDE is only available for ENTERPRISE organizations tiers and can only be enabled at service creation.

    • profileoptionalstring

      Custom instance profile. Only available for ENTERPRISE and BYOC organization tiers. Standard values: 'v1-default', 'v1-highmem-xs', 'v1-highmem-s', 'v1-highmem-m', 'v1-highmem-l', 'v1-highmem-xl'. BYOC services may instead use a dynamic BYOC profile configured for their infrastructure (e.g. 'v1-standard-byoc-4'); it requires byocId, and minReplicaMemoryGb and maxReplicaMemoryGb must both equal the profile's memory size. Use the serviceProfiles endpoint to list the profiles available to the organization.

    • transparentDataEncryptionKeyIdoptionalstring

      The ID of the Transparent Data Encryption key used for the service. This is only available if hasTransparentDataEncryption is true.

    • encryptionRoleIdoptionalstring

      The ID of the IAM role used for encryption. This is only available if hasTransparentDataEncryption is true.

    • complianceTypeoptionalhipaaorpci

      Type of regulatory compliance for service.

    • tagsoptionalarray ofobject

      Tags associated with the service.

      2 properties
      • keystringrequired

        Tag key. Must be alphanumeric with dashes, underscores and dots.

        maxLength: 128, minLength: 1, pattern: ^[a-zA-Z0-9._-]+$
      • valueoptionalstring

        Tag value. Must be alphanumeric with dashes, underscores and dots.

        maxLength: 256, pattern: ^[a-zA-Z0-9._-]+$
    • enableCoreDumpsoptionalboolean

      True if the service's underline infra is enabled for collecting core dumps. This is an experimental feature

    • scalingScheduleoptionalobject
      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
Navigation