Get Project Metrics

Scope: this page documents metrics and logs from the running application. GitHub build logs use separate endpoints in GitHub Builds.

Returns the usage metrics of the project (CPU, memory, etc).

GET /v1/project/:id/metrics

Path Parameters

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

Headers

Header	Required	Description
`x-api-key`	Yes	Project API Key
`x-organization-id`	Yes	Active project organization

Query Parameters (optional)

Parameter	Type	Description
`instance`	string	Specific instance identifier. When omitted, HTTP projects return aggregated network metrics.

Response

The uptime field represents the current instance or container uptime returned by the metrics endpoint. It should not be interpreted as application uptime, SLA, or public availability history.

{
  "status": "success",
  "message": "get metrics with success",
  "data": {
    "type": "application",
    "aggregate": true,
    "network": {
      "requests": 1200,
      "bytes_received": 420000,
      "bytes_sent": 1800000,
      "status_codes": {
        "200": 1160,
        "500": 5
      },
      "user_agents": {
        "Mozilla/5.0": 900,
        "curl/8.0": 300
      },
      "window_seconds": 300
    }
  }
}

Native metrics for Valkey projects

Valkey projects use the same metrics route with the instance parameter, but return a sanitized native snapshot. Check the project's capabilities before requesting it.

Check capabilities

GET /v1/project/:id/metrics/capabilities

For tiers with snapshot access, data returns the available groups, the refresh interval, and the absence of historical data:

{
  "data": {
    "access": "snapshot",
    "groups": [
      "resources",
      "capacity",
      "clients",
      "activity",
      "key_lifecycle",
      "profile",
      "reliability"
    ],
    "refresh_seconds": 60,
    "history": null
  }
}

The valkey_realtime, valkey_premium, and valkey_enterprise tiers provide snapshots. When access is none, do not request the snapshot; the Console shows observability as unavailable.

Request a snapshot

GET /v1/project/:id/metrics?instance=instance-1

The metrics object in data has the following shape. The top-level cpu and memory fields are legacy resource fields; native data is under valkey.

{
  "data": {
    "instance": "instance-1",
    "type": "valkey",
    "cpu": 0.25,
    "memory": 134217728,
    "observed_at": "2026-08-28T12:00:00.000Z",
    "availability": "available",
    "valkey": {
      "schema_version": 1,
      "profile": "cache",
      "availability": "available",
      "memory": {
        "used_bytes": 104857600,
        "peak_bytes": 125829120,
        "limit_bytes": 536870912,
        "fragmentation_ratio": 1.02
      },
      "clients": {
        "connected": 12,
        "blocked": 0
      },
      "activity": {
        "operations_per_second": 240,
        "input_bytes_per_second": 1048576,
        "output_bytes_per_second": 2097152
      },
      "keys": {
        "expired_total": 120,
        "evicted_total": 3
      },
      "uptime_seconds": 86400,
      "cache": {
        "hits_total": 3900,
        "misses_total": 100,
        "hit_ratio": 0.975
      },
      "reliability": {
        "replication": {
          "status": "not_applicable",
          "replicas_available": null,
          "replicas_expected": 1,
          "lag_seconds": null
        },
        "persistence": {
          "enabled": true,
          "status": "healthy",
          "last_success_at": "2026-08-28T11:59:55.000Z"
        }
      }
    }
  }
}

The optional cache and key_value fields depend on the project profile:

cache: hits_total, misses_total, and hit_ratio;
key_value: keys_total and keys_with_expiration.

Snapshot availability can be available, partial, stale, or unavailable. Fields without sufficient evidence return null; the API does not replace them with fabricated values.

When no valid snapshot exists, the response keeps the public metadata and returns valkey: null:

{
  "data": {
    "instance": "instance-1",
    "type": "valkey",
    "cpu": 0,
    "memory": 0,
    "observed_at": null,
    "availability": "unavailable",
    "valkey": null
  }
}

This capability does not provide historical data (history: null). Queue-specific metrics such as queue depth, item age, or consumer lag are not part of the verified snapshot.

Native PostgreSQL and MariaDB metrics

PostgreSQL and MariaDB projects on Premium+ plans use the same stable endpoints. Check capabilities before requesting an instance snapshot:

GET /v1/project/:id/metrics/capabilities
GET /v1/project/:id/metrics?instance=instance-1

Capabilities report access, available groups, and refresh interval. history: null means the capability provides only the latest snapshot, with no time-series retention or historical charts.

{
  "data": {
    "access": "snapshot",
    "groups": [
      "resources",
      "connections",
      "activity",
      "cache",
      "storage",
      "locks",
      "latency",
      "reliability"
    ],
    "refresh_seconds": 60,
    "history": null
  }
}

Snapshot envelope

The response preserves the existing route and returns a versioned envelope for each instance. This PostgreSQL example contains representative values; conditional fields may be null.

{
  "status": "success",
  "data": {
    "schema_version": 1,
    "project_id": "507f1f77bcf86cd799439011",
    "instance": "instance-1",
    "type": "postgresql",
    "observed_at": "2026-08-29T12:00:00.000Z",
    "collected_at": "2026-08-29T12:00:01.000Z",
    "availability": "available",
    "resource": {
      "cpu_usage_cores": 0.42,
      "memory_usage_bytes": 268435456,
      "storage_used_bytes": 2147483648,
      "storage_capacity_bytes": 10737418240
    },
    "native": {
      "connections": {
        "current": 12,
        "max": 100,
        "utilization_ratio": 0.12,
        "active": 3,
        "idle": 9
      },
      "activity": {
        "commits_total": 24000,
        "rollbacks_total": 120,
        "transactions_per_second": 18.5,
        "rows_returned_total": 980000,
        "rows_fetched_total": 310000,
        "rows_written_total": 42000,
        "temp_files_total": 7,
        "temp_bytes_total": 1048576
      },
      "cache": {
        "buffer_hits_total": 950000,
        "buffer_reads_total": 50000,
        "hit_ratio": 0.95
      },
      "storage": {
        "database_size_bytes": 1610612736
      },
      "locks": {
        "waiting_total": 1,
        "deadlocks_total": 2
      },
      "latency": {
        "average_query_latency_ms": null,
        "slow_queries_total": null
      },
      "reliability": {
        "up": true,
        "uptime_seconds": 86400,
        "wal_bytes_total": 734003200,
        "wal_bytes_per_second": 32768,
        "checkpoints_total": 36,
        "checkpoint_buffers_total": 4200,
        "role": "primary",
        "replicas_available": 1,
        "replicas_expected": 1,
        "lag_seconds": 0.4,
        "lag_bytes": 4096
      }
    }
  }
}

schema_version identifies the envelope version.
type distinguishes postgresql from mariadb; each project receives only its engine's groups.
observed_at is when values were observed on the instance.
collected_at is when the snapshot became available for retrieval.
resource contains CPU in cores and memory/storage in bytes.
native contains only product fields defined for the engine.

PostgreSQL fields

Group	Fields
Connections	`current`, `max`, `utilization_ratio`, `active`, `idle`
Activity and transactions	`commits_total`, `rollbacks_total`, `transactions_per_second`, `rows_returned_total`, `rows_fetched_total`, `rows_written_total`, `temp_files_total`, `temp_bytes_total`
Read cache	`buffer_hits_total`, `buffer_reads_total`, `hit_ratio`
Storage	`database_size_bytes`
Locks	`waiting_total`, `deadlocks_total`
Latency	`average_query_latency_ms`, `slow_queries_total`, when available
Health, WAL, and checkpoints	`up`, `uptime_seconds`, `wal_bytes_total`, `wal_bytes_per_second`, `checkpoints_total`, `checkpoint_buffers_total`
Replication	`role`, `replicas_available`, `replicas_expected`, `lag_seconds`, `lag_bytes`

MariaDB fields

Group	Fields
Connections and threads	`current`, `max`, `utilization_ratio`, `threads_connected`, `threads_running`, `aborted_connects_total`
Activity	`queries_total`, `questions_total`, `queries_per_second`, `bytes_received_per_second`, `bytes_sent_per_second`, `slow_queries_total`
Read cache	`buffer_pool_size_bytes`, `buffer_pool_data_bytes`, `buffer_pool_free_bytes`, `buffer_pool_dirty_pages`, `buffer_pool_reads_total`, `buffer_pool_read_requests_total`, `hit_ratio`
Redo and I/O	`log_writes_total`, `log_waits_total`, `fsyncs_total`, `io_per_second`, when available
Storage	`database_size_bytes`
Locks	`row_lock_waits_total`, `row_lock_time_ms_total`, `current_waits`, `deadlocks_total`
Latency	`average_query_latency_ms`, when available
Health	`up`, `uptime_seconds`
Replication	`status`, `replicas_available`, `replicas_expected`, `lag_seconds`

For MariaDB, threads_connected represents open sessions; threads_running represents threads doing work at sample time. The fields are not equivalent.

Counters, rates, ratios, and units

_total fields are cumulative counters since the last restart or reset.
_per_second fields are rates calculated between two valid samples.
After a reset, the related rate returns null until a new valid baseline exists; it never returns a negative value.
_ratio fields are fractions from 0 to 1.
Bytes are integers; latency uses milliseconds; lag uses seconds or bytes as indicated by the field name; CPU uses cores.
Read cache is the engine's internal cache and does not represent the operating system cache.

Availability and nullable fields

availability can be:

available: the sample completed;
partial: only some groups or fields were obtained;
stale: a previous valid sample is returned with its original timestamps;
unavailable: no valid sample can be presented.

A missing, unsupported, or uncomputable field returns null, never a synthetic zero. The snapshot presents aggregate values and does not include query text or parameters.

Get Project Logs

Returns the logs of the running project.

GET /project/:id/logs

Path Parameters

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

Query Parameters (optional)

Parameter	Type	Description
`instance`	string	Instance identifier used to return logs from a single container

Response

{
  "status": "success",
  "message": "get instances logs with success",
  "data": [
    "2024-01-15T10:30:00Z Starting application...\n2024-01-15T10:30:01Z Server listening on port 3000",
    "2024-01-15T10:30:05Z GET /health 200"
  ]
}

When instance is sent, data can be a single string containing the logs for the requested instance.

Examples

Get Metrics

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

Get Logs

curl -X GET "https://api.zenifra.com/v1/project/507f1f77bcf86cd799439011/logs?instance=abc" \
  -H "x-api-key: your-api-key" \
  -H "x-organization-id: your-organization-id"

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}

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

# Get logs
logs = requests.get(
    f"https://api.zenifra.com/v1/project/{PROJECT_ID}/logs",
    params={"instance": "abc"},
    headers=headers
).json()
print(logs)

On this page