/api/v1/status/history

Time-bucketed uptime history for building charts.

Time-bucketed uptime history for building charts. Supports per-service filtering and hourly/daily resolution.

Why use this

Common use case

Rendering a 90-day uptime bar chart on a public status page (the standard `https://status.example.com/` style). Also useful for SLA reporting to enterprise customers ('we maintained 99.95% uptime over the last 30 days') and for incident retrospectives ('show me the response-time spike around the 2026-04-22 throttle event').

Time-bucketed uptime history for charting — Phase 39+ system-status work product. Returns per-service health buckets (total_checks / healthy / degraded / down counts + uptime_pct + avg_response_ms) at hourly or daily resolution. EXEMPT (cost: 0) — safe for public-facing status-page polling. The health 3-tier classification (healthy/degraded/down) maps directly to status-page bar colors (green/yellow/red). The meta.warning field surfaces clamp messages (e.g. when ?resolution=hourly&days=30 would produce 720 buckets, server clamps to daily and warns). Pair with GET /api/v1/status for the current-state snapshot view of the same services. Real example: the 2026-04-22 sample bucket (uptime 88.75%, avg_response_ms 287) reflects the Hostinger CPU-throttle incident on that date — a useful reference point for what 'degraded' looks like in the time series. For news/changelog of incidents pair with the public /dev/changelog page.

Parameters

Name	In	Required	Default	Allowed	Description	Example
service	query	optional	—	—	Filter by service name. Valid values: `main_api`, `insider_api`, `postgres_db`, `redis`, `sec_worker`, `sec_13f_worker`, `news_daemon`, `sec_gateway`, `frontend`. Omit for ALL services (returns multi-service rollup). Internal service names match the docker-compose container names so they're stable across deploys.	main_api
days	query	optional	30	—	History window in days (max 90). Server caps at 90 — values > 90 silently clamp.	—
resolution	query	optional	daily	—	Bucket size: `hourly` (good for 1-7 day windows; up to 168 buckets) or `daily` (good for 30-90 day windows; up to 90 buckets). The endpoint warns via the `meta.warning` field if the (resolution, days) combination would produce > 200 buckets (e.g. `hourly + days=30` = 720 buckets is auto-clamped to daily server-side).	—

Response schema

Field	Type	Nullable	Description
days	integer	no	Echoed history window in days.
resolution	string	no	Echoed bucket size — `hourly` or `daily` (after server-side clamp if applicable).
history	object	no	Map of `service_name -> [bucket]` arrays. When `?service=...` is filtered, only that service's array is present; otherwise all services are included. Each service's array is in CHRONOLOGICAL order (oldest bucket first, newest last) — natural for left-to-right chart rendering.
history.{service}[].timestamp	string	no	ISO 8601 UTC timestamp of the BUCKET START. For hourly buckets: `2026-05-02T18:00:00Z` (top of the hour). For daily buckets: `2026-05-02T00:00:00Z` (UTC midnight).
history.{service}[].total_checks	integer	no	Total number of health-checks performed in the bucket. The watchdog runs every 60s by default — so an hourly bucket has ~60 checks and a daily bucket has ~1,440. Useful as the denominator for any custom uptime calculation.
history.{service}[].healthy	integer	no	Count of `healthy` (200 + < 1s response) checks in the bucket.
history.{service}[].degraded	integer	no	Count of `degraded` (200 but slow >1s, or 5xx but auto-recovered) checks in the bucket. Degraded counts indicate intermittent issues — surfaced as a yellow bar on status-page UIs.
history.{service}[].down	integer	no	Count of `down` (connection-refused, timeout, sustained 5xx) checks in the bucket. Surfaced as a red bar on status-page UIs.
history.{service}[].uptime_pct	number	no	Convenience field — `round(healthy / total_checks * 100, 2)`. Display-ready for status-page bar tooltips (e.g. 'May 2: 99.86% uptime').
history.{service}[].avg_response_ms	integer	no	Bucket-mean response time in milliseconds. Useful for surfacing latency-spike events on a separate chart line.
meta	object	no	Query echo + warnings: `{ generated_at: string, services_included: string[], warning: string\|null }`. The `warning` field surfaces messages like `"resolution clamped from hourly to daily — bucket count would exceed 200"` when the (resolution, days) combination produces too many buckets.

Sample response

"days": 30
"resolution": "daily"
"history":
- "main_api":
}
"meta":
- "generated_at": "2026-05-02T20:15:00Z"
- "services_included":
- "warning": null
}

}

Errors

Status	Label	Description
200	OK	Request succeeded.
400	Bad Request	Invalid query, body, or path parameter.
401	Unauthorized	Missing or invalid Authorization header / api_Token.
402	Payment Required	Insufficient token balance for this call. Top up
429	Too Many Requests	Rate limit exceeded for your tier (see /pricing for tier limits). Tier limits
500	Server Error	Unexpected server-side failure. Retry with backoff; report if persistent.

Code samples

Reveal credentials

curl "https://api.finradar.ai/api/v1/status/history" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Generate an API key in /account/credentials to run live queries (literal YOUR_API_KEY placeholder shown until then).