Skip to main content

Monitoring

Stateway provides operational metrics for observing the health of your processes, tasks, service jobs, and webhooks in real time.

Tenant Summary​

Returns operational metrics scoped to the current tenant. Any API key can call this endpoint — no special scope is required.

curl https://api.stateway.io/v1/monitoring/summary \
  -H "X-API-Key: sw_live_your_key"
{
  "data": {
    "instances": {
      "pending": 0,
      "running": 12,
      "suspended": 1,
      "completed": 847,
      "terminated": 3,
      "error": 2
    },
    "humanTasks": {
      "pending": 5,
      "claimed": 2,
      "completed": 204,
      "cancelled": 1
    },
    "serviceTaskJobs": {
      "pending": 0,
      "running": 3,
      "completed": 1203,
      "failed": 7,
      "timeout": 1
    },
    "timerJobs": {
      "scheduled": 4,
      "overdue": 0
    },
    "webhookDeliveries": {
      "pending": 2,
      "success": 980,
      "failed": 5
    },
    "redis": {
      "webhookStreamLength": 12,
      "webhookStreamPending": 2,
      "connectedClients": 3,
      "usedMemoryBytes": 5242880
    }
  }
}

What each field means​

instances — current counts by status across all process instances.

humanTasks — current counts by status for human tasks.

serviceTaskJobs — counts for automated task executions (HTTP calls). failed means exhausted retries; timeout means the async timeout was reached.

timerJobs — scheduled timers are awaiting their fire time; overdue timers passed their fire time but have not yet been processed (indicates a polling lag).

webhookDeliveries — delivery attempts across all subscriptions. pending means queued for dispatch; failed means all retry attempts exhausted.

redis — Redis stream and connection stats. webhookStreamPending counts messages not yet acknowledged by a consumer.

System-Wide Metrics​

Returns the same structure aggregated across all tenants. Requires the admin scope.

curl https://api.stateway.io/v1/monitoring/system \
  -H "X-API-Key: sw_live_admin_key"

The response shape is the same as /monitoring/summary, with an additional tenants field:

{
  "data": {
    "tenants": 42,
    "instances": { ... },
    "humanTasks": { ... },
    ...
  }
}

This endpoint is intended for platform operators. A 403 FORBIDDEN is returned for API keys without the admin scope.

Prometheus Metrics​

The /metrics endpoint exposes Prometheus-formatted metrics for scraping:

GET /metrics

This endpoint is unauthenticated and intended for internal scraping by your monitoring infrastructure (Prometheus, Grafana, etc.). It should not be exposed publicly — restrict access at the network or ingress level.

Monitoring Patterns​

Detect stalled processes​

A non-zero instances.error count indicates processes that need attention. Combine with GET /instances?status=error to get the list and inspect each instance's error field.

Detect overdue timers​

A non-zero timerJobs.overdue count indicates the timer polling loop is behind. This is a leading indicator of processing lag.

Monitor webhook reliability​

Track webhookDeliveries.failed over time. A growing count indicates consistently unreachable webhook endpoints — check your subscription URLs and retry configuration.

Track task backlog​

humanTasks.pending represents unclaimed tasks. A growing backlog may indicate insufficient task assignees or a process design issue.