Metrics API

Raw and aggregated performance metrics collected from SDK agents and services.

All metric data is stored in MongoDB.


GET /api/metrics

Returns raw metrics records, sorted by timestamp descending (up to 100). Can be filtered by projectId.

Auth: Bearer token (any authenticated user)

Query Parameters:

Param Type Description
projectId uuid Filter by project

Response 200:

[
  {
    "_id": "mongo-id",
    "projectId": "uuid",
    "environment": "development",
    "registrationId": "uuid",
    "cpuPct": 12.5,
    "memoryMb": 256,
    "heapMb": 160,
    "uptimeS": 3600,
    "requestCount": 42,
    "avgResponseMs": 15,
    "p95ResponseMs": 40,
    "errors4xx": 0,
    "errors5xx": 0,
    "dbHealth": {
      "postgres": { "activeCount": 2, "idleCount": 8, "status": "connected" }
    },
    "timestamp": "2026-07-01T12:00:00.000Z"
  }
]

GET /api/metrics/aggregated

Returns aggregated averages for the most recent 20 metric records. Includes CPU average, memory average, and error rate.

Auth: Bearer token (any authenticated user)

Query Parameters:

Param Type Description
projectId uuid Filter by project

Response 200:

{
  "cpuAvg": 15.3,
  "memoryAvg": 280.5,
  "errorRate": 0.5
}

GET /api/sdk/api-metrics

Returns aggregated API performance metrics with p50, p95, and p99 latency percentiles. Metrics are grouped by route and HTTP method.

Auth: Bearer token (any authenticated user)

Query Parameters:

Param Type Description
projectId uuid Required — Filter by project
environment string Filter by environment name
from string ISO date — start of range
to string ISO date — end of range

Response 200:

{
  "metrics": [
    {
      "_id": {
        "route": "/api/users",
        "method": "GET"
      },
      "count": 150,
      "avgDuration": 42.5,
      "errors4xx": 2,
      "errors5xx": 0,
      "lastSeen": "2026-07-01T12:00:00.000Z",
      "p50": 35,
      "p95": 95,
      "p99": 200
    }
  ]
}

POST /api/sdk/api-metrics

Ingests API metrics from SDK agents. Accepts an array of metric records. Used internally by the SDKs.

Auth: SDK token (Bearer token starting with sdk-)

Request Body:

{
  "projectId": "uuid",
  "metrics": [
    {
      "route": "/api/users",
      "method": "GET",
      "statusCode": 200,
      "durationMs": 42,
      "memoryDeltaBytes": 1024,
      "environment": "production",
      "timestamp": "2026-07-01T12:00:00.000Z"
    }
  ]
}

Response 200:

{ "saved": 1 }

Error Codes

Status Error Description
400 projectId required Missing required query param