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
Monthly or yearly plan	May be rejected; dynamic scaling is intended for hourly billing
`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 or plan does not allow dynamic scaling	Check that the project is running and billed hourly
`500`	Operational failure while applying scaling	Retry or contact support

Next Steps

Check Metrics and Logs to validate the new instance.
Use Lifecycle to stop or resume a project.
Review Storage before increasing instances with persistent volumes.

On this page