Metrics API

The Metrics API provides three endpoints for observability: aggregate summary statistics, time-series throughput data, and real-time per-queue depth. These power the Zeridion Flare dashboard and can be used to build custom monitoring integrations.

Base URL: https://api.zeridion.com

All endpoints require Bearer token authentication and are subject to rate limits.

---

GET /v1/metrics/summary

Retrieve aggregate job statistics for a given time period.

Request

GET /v1/metrics/summary?period=24h
Authorization: Bearer <api_key>

Query Parameters

Param	Type	Default	Allowed values
period	string	24h	1h, 24h, 7d, 30d

Response

200 OK

{
  "total": 1547,
  "pending": 12,
  "scheduled": 3,
  "processing": 5,
  "succeeded": 1480,
  "failed": 38,
  "cancelled": 7,
  "dead_letter": 2,
  "success_rate": 0.9737,
  "avg_duration_ms": 842.5,
  "period": "24h"
}

Field	Type	Description
total	integer	Total jobs created within the period (sum of all state counts)
pending	integer	Jobs created in the period whose current state is pending
scheduled	integer	Jobs created in the period whose current state is scheduled
processing	integer	Jobs created in the period whose current state is processing
succeeded	integer	Jobs created in the period whose current state is succeeded
failed	integer	Jobs created in the period whose current state is failed
cancelled	integer	Jobs created in the period whose current state is cancelled
dead_letter	integer	Jobs created in the period whose current state is dead_letter
success_rate	number	Success ratio: succeeded / (succeeded + failed + dead_letter), rounded to 4 decimal places
avg_duration_ms	number	Average execution duration in milliseconds, or null if no completed jobs
period	string	Echoed period value

---

GET /v1/metrics/throughput

Retrieve time-series throughput data bucketed by a configurable granularity. Useful for charting job volume over time.

Request

GET /v1/metrics/throughput?period=24h&granularity=hour
Authorization: Bearer <api_key>

Query Parameters

Param	Type	Default	Allowed values
period	string	24h	1h, 24h, 7d, 30d
granularity	string	auto	minute, hour, day

When granularity is omitted, it is automatically resolved from the period:

Period	Auto-granularity
1h	minute
24h	hour
7d	hour
30d	day

Response

200 OK

{
  "period": "24h",
  "granularity": "hour",
  "data": [
    {
      "timestamp": "2026-03-18T00:00:00Z",
      "enqueued": 45,
      "succeeded": 42,
      "failed": 3
    },
    {
      "timestamp": "2026-03-18T01:00:00Z",
      "enqueued": 67,
      "succeeded": 65,
      "failed": 2
    }
  ]
}

Field	Type	Description
period	string	Echoed period value
granularity	string	Resolved granularity
data	array	Array of time-bucketed throughput entries

Throughput bucket fields

Field	Type	Description
timestamp	string (ISO 8601)	Start of the time bucket
enqueued	integer	Jobs enqueued during this bucket
succeeded	integer	Jobs that succeeded during this bucket
failed	integer	Jobs that failed or dead-lettered during this bucket (completions with state Failed or DeadLetter)

---

GET /v1/metrics/queues

Retrieve the current depth of all queues. Shows how many jobs are pending, processing, or scheduled in each queue.

Request

GET /v1/metrics/queues
Authorization: Bearer <api_key>

No query parameters.

Response

200 OK

{
  "queues": [
    {
      "name": "default",
      "pending": 8,
      "processing": 3,
      "scheduled": 2
    },
    {
      "name": "email",
      "pending": 15,
      "processing": 5,
      "scheduled": 0
    },
    {
      "name": "maintenance",
      "pending": 0,
      "processing": 0,
      "scheduled": 1
    }
  ]
}

Field	Type	Description
name	string	Queue name
pending	integer	Jobs ready to be claimed by a worker
processing	integer	Jobs currently being executed
scheduled	integer	Jobs scheduled for future execution

Returns an empty queues array if no queues have any active jobs.

---

Usage Notes

• Dashboard integration: The Zeridion Flare dashboard calls these endpoints to render the overview charts, throughput graphs, and queue depth panels. You can build similar visualizations for your own monitoring stack.
• Polling frequency: For real-time dashboards, poll /v1/metrics/summary and /v1/metrics/queues every 10–30 seconds. For throughput charts, poll less frequently (every 1–5 minutes).
• See the Monitoring guide for setting up OpenTelemetry alongside these endpoints.