Project Instances

Use these endpoints to discover active instances and change the number of replicas for a project. They are useful for scaling automation, cost-saving routines, and internal operations dashboards.

Required permissions

Listing requires project.read on project:<project-id>. Changing the count requires project.instances.update on the same project. owner has full access; assistant, member, and organization API Keys need the grant for the action.

Headers

Header	Required	Description
`x-api-key` or `Authorization`	Yes	Organization API Key or user token
`x-organization-id`	With a user token	Active project organization. Not needed with an organization API key
`Content-Type: application/json`	Yes	Required only for `PATCH`

List Instances

Returns the current project instance identifiers.

GET /v1/project/:id/instances

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

Path Parameters

Parameter	Type	Description
`id`	string	Project ID

Response

{
  "status": "success",
  "message": "get instances with success",
  "data": [
    { "instance": "abc" },
    { "instance": "def" }
  ]
}

For Key-Value, Cache, and Queue projects, instances are listed as instance-1, instance-2, and so on, with a status field. Scheduled Jobs have no permanent instances and respond 409.

Use the instance value in metrics and logs calls when you want to inspect a specific instance.

Change Instance Count

Changes the number of project replicas.

PATCH /v1/project/:id/instances

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

Body

Field	Type	Required	Description
`instances`	number	Yes	New instance count. Must be a positive integer.

Example

{
  "instances": 3
}

Response

{
  "status": "success",
  "message": "project instances changed with success"
}

Operational Rules

Situation	Result
`instances` equals the current value	Returns `200` with a plain-text `OK` body and no change
`instances` equals `0`	Rejected with `400` (validation). Use Lifecycle to stop the project
Project is stopped	Rejected with `409`. Use `/resume` before scaling
HTTP autoscaling enabled	Rejected with `409`. Disable HTTP Autoscaling before manual changes
Monthly or yearly plan	Rejected with `409`: manual scaling is only available with hourly billing
`db-free` plan	Does not allow dynamic instance changes (`409`)
Valkey	Rejected with `409`: capacity is defined by the selected plan
Scheduled Job	Rejected with `409`
Free plan	Limit of 2 instances in total; above that, `409`
Capacity unavailable	`409` (requested capacity unavailable) or `503` (capacity temporarily unavailable); try again shortly
MariaDB	Requires exactly 3 instances

Examples

curl

curl -X GET "https://api.zenifra.com/v1/project/507f1f77bcf86cd799439011/instances" \
  -H "x-api-key: your-api-key" \
  -H "x-organization-id: your-organization-id"

curl -X PATCH "https://api.zenifra.com/v1/project/507f1f77bcf86cd799439011/instances" \
  -H "x-api-key: your-api-key" \
  -H "x-organization-id: your-organization-id" \
  -H "Content-Type: application/json" \
  -d '{"instances": 3}'

Python

import requests

API_KEY = "your-api-key"
ORGANIZATION_ID = "your-organization-id"
PROJECT_ID = "507f1f77bcf86cd799439011"

headers = {"x-api-key": API_KEY, "x-organization-id": ORGANIZATION_ID}

instances = requests.get(
    f"https://api.zenifra.com/v1/project/{PROJECT_ID}/instances",
    headers=headers
).json()

scale = requests.patch(
    f"https://api.zenifra.com/v1/project/{PROJECT_ID}/instances",
    headers=headers,
    json={"instances": 3}
).json()

Common Errors

Code	Likely reason	How to fix
`400`	`instances` is missing, invalid, or `0`; MariaDB with a count other than 3	Send a positive integer and use `/stop` to stop the project
`404`	Project not found	Check Project ID, API Key, and organization
`409`	Current state, plan, billing mode, project type, capacity, or active autoscaling does not allow manual scaling	Check that the project is running and autoscaling is disabled
`503`	Capacity temporarily unavailable	Try again shortly
`500`	Operational failure while applying scaling	Retry or contact support

Next Steps

Check Metrics and Logs to validate the new instance.
Use HTTP Autoscaling when the application must absorb spikes automatically.
Use Lifecycle to stop or resume a project.
Review Storage before increasing instances with persistent volumes.

On this page