HTTP Autoscaling

Use this endpoint to configure autoscaling for paid HTTP applications. The project keeps a reserved minimum instance count and can increase instances automatically during traffic spikes.

Required permissions

Configuring autoscaling requires project.instances.update on project:<project-id>. Reading scaling events requires project.metrics.read on the same project. owner has full access; assistant, member, and organization API Keys need the specific scope.

Headers

HeaderRequiredDescription
x-api-key or AuthorizationYesOrganization API Key or user token
x-organization-idWith a user tokenActive project organization. Not needed with an organization API key
Content-Type: application/jsonYesRequired for PATCH

Update Autoscaling

PATCH /v1/project/:id/autoscaling

Rate limit: 20 requests every 5 minutes (counted per source IP).

Body

FieldTypeRequiredDescription
enabledbooleanYestrue enables or updates; false disables
min_instancesintegerWhen enablingReserved minimum instances (positive integer)
max_instancesintegerWhen enablingMaximum instances allowed during spikes (positive integer)
target_cpu_utilization_percentintegerNoTarget CPU, from 1 to 100. Default: 70
target_memory_utilization_percentintegerNoTarget memory, from 1 to 100. Default: 80

max_instances must be greater than or equal to min_instances. With enabled: false, sending any other field returns 400.

Enable or Update

{
  "enabled": true,
  "min_instances": 2,
  "max_instances": 8,
  "target_cpu_utilization_percent": 70,
  "target_memory_utilization_percent": 80
}

Disable

{
  "enabled": false
}

Response

{
  "status": "success",
  "message": "project autoscaling updated with success",
  "data": {
    "autoscaling": {
      "enabled": true,
      "min_instances": 2,
      "max_instances": 8,
      "target_cpu_utilization_percent": 70,
      "target_memory_utilization_percent": 80
    }
  }
}

Event History

GET /v1/project/:id/autoscaling/events

Rate limit: 100 requests per minute (counted per source IP).

Returns the paginated history of scale up and scale down events recorded by Zenifra. Use this endpoint for audit trails, support, and traffic spike analysis.

Query

FieldTypeRequiredDescription
directionstringNoFilters by scale_up or scale_down
fromISO dateNoStart of the period
toISO dateNoEnd of the period
pagenumberNoPage. Default: 1
limitnumberNoItems per page. Default: 50, maximum: 100

Response

{
  "status": "success",
  "message": "get project autoscaling events with success",
  "data": {
    "events": [
      {
        "id": "6a24f7...",
        "direction": "scale_up",
        "previous_instances": 2,
        "new_instances": 5,
        "desired_instances": 5,
        "min_instances": 2,
        "max_instances": 8,
        "trigger_metric": "cpu",
        "current_cpu_utilization_percent": 91,
        "target_cpu_utilization_percent": 70,
        "current_memory_utilization_percent": 62,
        "target_memory_utilization_percent": 80,
        "reason": "increased_capacity",
        "message": "Automatic scaling increased the project instance count.",
        "occurred_at": "2026-06-05T21:40:00.000Z"
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 50,
      "total": 1,
      "total_pages": 1
    }
  }
}

The history is retained for 13 months.

Billing

For hourly projects, billing uses observed instances during the billing period.

For monthly or yearly projects, the reserved minimum is part of the main contract. Instances above the minimum are billed per instance-hour, using the contract price converted to an hourly rate: the monthly price divided by 720 or the yearly price divided by 8,760.

Rules

SituationResult
Project is not HTTPRejected
Project is stoppedRejected
Plan does not allow autoscalingRejected
Manually changing instances while autoscaling is enabledRejected with 409

Common Errors

StatusCodeWhen it happens
400—The project is not HTTP, or the body is invalid
403AUTOSCALING_NOT_AVAILABLE_FOR_PLANThe current plan does not allow autoscaling
409PROJECT_MUST_BE_RUNNINGThe project must be running before autoscaling can be changed
409AUTOSCALING_REQUIRES_SHARED_STORAGEThe project needs shared storage to use autoscaling
409PROJECT_LIFECYCLE_OPERATION_IN_PROGRESSAnother project operation is in progress
429AUTOSCALING_UPDATE_IN_PROGRESSAnother autoscaling update is already running for the project
429AUTOSCALING_TOGGLE_COOLDOWN_ACTIVEAutoscaling was enabled or disabled recently; the response includes retry_after_seconds
503AUTOSCALING_TEMPORARILY_UNAVAILABLEAutoscaling is temporarily unavailable; try again shortly

Next Steps

Last updated on

Project Instances

List and change project instance count through the API, including scaling rules, hourly plans, and invalid states.

Application health check

Read, enable, or disable the health check of an HTTP application through the API and list the failures recorded in the last 30 days, with pagination.

On this page

HTTP AutoscalingRequired permissionsHeadersUpdate AutoscalingBodyEnable or UpdateDisableResponseEvent HistoryQueryResponseBillingRulesCommon ErrorsNext Steps