# System Status — Finradar API
> Version: 3.61.0 | Generated: 2026-06-20 | Content Hash: 41a5c6a2
> Fetch this file at: https://uat.finradarapi.com/llms/system-status.txt

## Authentication
All endpoints require an API key. Pass it via query parameter `?apiKey=YOUR_KEY` or header `X-API-Key: YOUR_KEY`. WebSocket endpoints accept the key in the `token` auth payload or query parameter.

---

## System Status

Public service health and uptime monitoring. No authentication required.

### GET /api/v1/status

Current health status of all monitored services with 30-day and 90-day uptime percentages.

**Token cost:** 0 (EXEMPT — auth / billing / account / admin / health)

**Response fields:**
- `overall` (string): Aggregate platform-wide status — `operational` (all services healthy), `degraded` (one or more services show elevated latency but functional), `partial_outage` (one or more services down but most operational), `major_outage` (multiple services down). Use as the canonical 'is FinRadar healthy?' single-field signal. Color-code dashboards accordingly (green/amber/orange/red).
- `services` (array): Array of per-service status entries. Covers ~10-15 monitored services: `main_api`, `insider_module`, `13f_worker`, `postgres_db`, `redis`, `sec_gateway`, `sec_watchdog`, etc. Each row carries response time, uptime stats, and last-check timestamp.
- `services[].name` (string): Canonical service identifier (e.g. `main_api`, `insider_module`, `13f_worker`, `postgres_db`, `redis`, `sec_gateway`). Stable across versions — safe for use as join key in monitoring integrations.
- `services[].status` (string): Per-service status — `operational` (healthy), `degraded` (elevated latency but functional, typically > p95 latency threshold), `down` (failing health check). Watchdog runs the check every 60 seconds; values reflect the most-recent successful check.
- `services[].uptime_30d_pct` (number): Rolling 30-day uptime percentage (0.0-100.0, computed as `healthy_checks / total_checks * 100`). Internal SLO target is 99.9% on customer-facing services. Values below 99.5% should trigger reliability investigation.
- `services[].last_check_at` (string): ISO-8601 UTC timestamp of the most recent watchdog health check. Should always be within the last 60 seconds — values older than 5 minutes indicate the watchdog itself is degraded (a meta-failure that bypasses normal alerting).
- `data_freshness` (object): Data-freshness metrics complementing service-uptime: `{ last_filing_at, queue_depth, last_13f_batch_at, last_xbrl_run_at, last_news_at }`. Use to detect ingestion staleness even when services are technically 'up'. A `last_filing_at` more than 10 minutes stale during ET market hours is the canonical ingestion-pipeline alert.
- `as_of` (string): ISO-8601 UTC timestamp the status snapshot was generated server-side. Cached for 30 seconds at the gateway — polling more aggressively than 1 Hz returns stale-but-cheap data.

**Since:** v2.1.0

**Utility:** Public service-health probe — current operational status of every FinRadar service (main_api, insider_module, 13f_worker, postgres_db, redis, etc.) with rolling 30-day and 90-day uptime percentages. Also includes data-freshness metrics (last filing accepted, queue depth, last 13F batch parsed) so customers can verify ingestion is current BEFORE making decisions on the underlying data — a green status with `last_filing_at` 12 hours stale is misleading without this layer. No authentication required, free (`cost: 0`). The right endpoint for: status pages, monitoring dashboards, operational alerting integrations, and pre-flight checks on automation pipelines. Pair with `/api/v1/status/history` for time-bucketed historical uptime charts.

**Use case:** Building a status page or monitoring dashboard that shows service health at a glance.

**Sample response:**
```json
{
  "status": "operational",
  "services": {
    "main_api": {
      "status": "healthy",
      "response_time_ms": 45,
      "uptime_30d": 99.95,
      "uptime_90d": 99.87,
      "checked_at": "2026-03-14T12:00:00Z"
    },
    "postgres_db": {
      "status": "healthy",
      "response_time_ms": 12,
      "uptime_30d": 100,
      "uptime_90d": 99.99,
      "checked_at": "2026-03-14T12:00:00Z"
    },
    "redis": {
      "status": "healthy",
      "response_time_ms": 3,
      "uptime_30d": 100,
      "uptime_90d": 100,
      "checked_at": "2026-03-14T12:00:00Z"
    }
  },
  "checked_at": "2026-03-14T12:00:00Z"
}
```

### GET /api/v1/status/history

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

**Token cost:** 0 (EXEMPT — auth / billing / account / admin / health)

**Response fields:**
- `days` (integer): Echoed history window in days.
- `resolution` (string): Echoed bucket size — `hourly` or `daily` (after server-side clamp if applicable).
- `history` (object): 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): 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): 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): Count of `healthy` (200 + < 1s response) checks in the bucket.
- `history.{service}[].degraded` (integer): 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): 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): 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): Bucket-mean response time in milliseconds. Useful for surfacing latency-spike events on a separate chart line.
- `meta` (object): 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.

**Since:** v2.1.0

**Utility:** 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. Pair with [GET /api/v1/status](/docs/resources/system-status/get-status) for the current-state snapshot (this endpoint is for historical trend visualization only).

**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').

**Parameters:**
- `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.
- `days` (query, optional, default: 30): History window in days (max 90). Server caps at 90 — values > 90 silently clamp.
- `resolution` (query, optional, default: 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).

**Sample response:**
```json
{
  "days": 30,
  "resolution": "daily",
  "history": {
    "main_api": [
      {
        "timestamp": "2026-04-03T00:00:00Z",
        "total_checks": 1440,
        "healthy": 1438,
        "degraded": 2,
        "down": 0,
        "uptime_pct": 99.86,
        "avg_response_ms": 52
      },
      {
        "timestamp": "2026-04-04T00:00:00Z",
        "total_checks": 1440,
        "healthy": 1440,
        "degraded": 0,
        "down": 0,
        "uptime_pct": 100,
        "avg_response_ms": 48
      },
      {
        "timestamp": "2026-04-22T00:00:00Z",
        "total_checks": 1440,
        "healthy": 1278,
        "degraded": 132,
        "down": 30,
        "uptime_pct": 88.75,
        "avg_response_ms": 287
      }
    ]
  },
  "meta": {
    "generated_at": "2026-05-02T20:15:00Z",
    "services_included": [
      "main_api"
    ],
    "warning": null
  }
}
```