Project Instances

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

Headers

Header	Required	Description
`x-api-key`	Yes	Project API Key
`x-organization-id`	Yes	Active project organization
`Content-Type: application/json`	Yes	Required only for `PATCH`

List Instances

Returns the current project instance identifiers.

GET /project/:id/instances

Path Parameters

Parameter	Type	Description
`id`	string	Project ID (ObjectId)

Response

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

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

Change Instance Count

Changes the number of project replicas.

PATCH /project/:id/instances

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 no meaningful change
`instances` equals `0`	Rejected. Use Lifecycle to stop the project
Project is stopped	Rejected. Use `/resume` before scaling
HTTP autoscaling enabled	Rejected. Disable HTTP Autoscaling before manual changes
Monthly or yearly plan	May be rejected for manual scaling; prefer autoscaling when the plan allows spikes
`db-free` plan	Does not allow dynamic instance changes
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`	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, or active autoscaling does not allow manual scaling	Check that the project is running and autoscaling is disabled
`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