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/flare/v1

All endpoints require Bearer token authentication and are subject to rate limits. Every response carries the standard X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers — see Rate Limits for the budget per plan.

---

GET /flare/v1/metrics/summary

Retrieve aggregate job statistics for a given time period.

Request

GET /flare/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 /flare/v1/metrics/throughput

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

Request

GET /flare/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,
      "p50_ms": 180.0,
      "p95_ms": 420.0,
      "p99_ms": 980.5
    },
    {
      "timestamp": "2026-03-18T01:00:00Z",
      "enqueued": 67,
      "succeeded": 65,
      "failed": 2,
      "p50_ms": 165.0,
      "p95_ms": 390.0,
      "p99_ms": null
    }
  ]
}

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)
p50_ms	number or null	50th-percentile (median) execution duration for jobs that completed inside the bucket (state Succeeded, Failed, or DeadLetter) and recorded a DurationMs. Computed via linear interpolation between the two nearest samples. null when the bucket has no completed-with-duration job.
p95_ms	number or null	95th-percentile execution duration; same population and interpolation rule as p50_ms. null when fewer than 1 completion in the bucket.
p99_ms	number or null	99th-percentile execution duration; same population and interpolation rule as p50_ms. null when fewer than 1 completion in the bucket.

---

GET /flare/v1/metrics/queues

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

Request

GET /flare/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.

---

GET /flare/v1/metrics/job-types

Retrieve the top-N job types by volume within a time period, with per-type success rates and average durations. Powers the "Top job types" chart on the dashboard.

Request

GET /flare/v1/metrics/job-types?period=24h&limit=10
Authorization: Bearer <api_key>

Query Parameters

Param	Type	Default	Allowed values
period	string	24h	1h, 24h, 7d, 30d
limit	integer	10	1–100

Response

200 OK

{
  "period": "24h",
  "data": [
    {
      "job_type": "email.send",
      "total": 1234,
      "succeeded": 1200,
      "failed": 30,
      "cancelled": 4,
      "avg_duration_ms": 145.0,
      "success_rate": 0.9756
    },
    {
      "job_type": "pdf.render",
      "total": 87,
      "succeeded": 80,
      "failed": 7,
      "cancelled": 0,
      "avg_duration_ms": 820.5,
      "success_rate": 0.9195
    }
  ]
}

Results are ordered by total descending (highest-volume job type first).

Field	Type	Description
period	string	Echoed period value
data	array	Up to limit job type rows ordered by total volume descending

Job type row fields

Field	Type	Description
job_type	string	The job type string (e.g. "email.send")
total	integer	Total jobs of this type created within the period
succeeded	integer	Jobs that reached the succeeded state
failed	integer	Jobs that reached failed or dead_letter state
cancelled	integer	Jobs that were cancelled
avg_duration_ms	number	Average execution duration in milliseconds; omitted when no completions have a duration
success_rate	number	succeeded / (succeeded + failed), rounded to 4 decimal places; 0 when denominator is 0. Note: this denominator differs from GET /metrics/summary — the summary endpoint includes dead_letter in the denominator (so a project with retries that ultimately dead-letter looks worse on the summary card than on this per-type breakdown). The job-types denominator excludes dead-letter so per-type retries are not double-counted against a single bucket.

---

Usage Notes

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

See also

• Monitoring guide — OpenTelemetry, log shipping, and dashboard patterns
• Rate Limits — polling-frequency budgets when calling these endpoints frequently
• Errors — rate_limit_exceeded and other failure modes