# Main API — Finradar API
> Version: 3.61.0 | Generated: 2026-06-20 | Content Hash: 3df98da7
> Fetch this file at: https://uat.finradarapi.com/llms/main-api.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.

---

## Main API

General platform statistics and reference data.

### GET /api/v1/stats

Get database and ingestion statistics.

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

**Response fields:**
- `total_filings` (integer): Cumulative count of SEC filings successfully accepted and persisted to the `filings` table. Covers Forms 3/4/5, 13F-HR/NT, 13D/G, 8-K, 10-K/Q, S-1, 20-F, and ~340 other root form types. Increments roughly +5K/day off-season and +50K/day during 13F deadline windows.
- `total_insiders` (integer): Distinct count of Section 16 insider entities (officers, directors, 10%+ owners) in the `insiders` table. Typically ~85K-100K active insiders.
- `total_holdings_13f` (integer): Total row count in the `form_13f_holdings` table — every (filer, issuer, period) row across all 13F filings. Typical magnitude: ~300M-400M rows across the full historical window.
- `total_tickers` (integer): Distinct ticker count in the canonical catalog. Typical: ~26K post v3.11.0 catalog expansion (was ~7,968 prior).
- `total_endpoints_documented` (integer): Count of distinct endpoints documented in apiDocs.js — the value surfaced on the docs page as 'X endpoints documented'. v5.0 milestone target: 156+ endpoints.
- `last_filing_at` (string): ISO 8601 UTC timestamp of the most-recent successfully-ingested filing. Lag should be < 60s during ET market hours; values older than ~10 minutes outside the SEC's overnight quiet-window (10pm-6am ET) indicate an ingestion-pipeline alert.
- `last_13f_quarter` (string): Most-recent calendar quarter-end (`YYYY-MM-DD`) for which 13F-HR filings have been processed. Updated within ~1h of the SEC's 45-day-after-quarter-end filing deadline. Use to surface 'as of Q1 2026' on holdings drill-downs.
- `request_id` (string): Server-generated request identifier for distributed-tracing / support-ticket attribution.
- `timestamp` (string): ISO 8601 UTC timestamp of the response generation.

**Since:** v1.0.0

**Utility:** Lightweight platform-level metrics endpoint — total filings tracked, total endpoints documented, total tickers in the catalog, last-ingestion timestamp. EXEMPT (`cost: 0`). The cheapest 'is FinRadar alive AND has fresh data?' probe — pair with [GET /api/v1/status](/docs/resources/system-status/get-status) for service-level health rollups and [GET /api/v1/facts](/docs/home/main-api/get-facts) for the per-form-type 90-day breakdown. Designed to be safe to poll at 60-second cadence from dashboard widgets without affecting plan budget.

**Use case:** Dashboard widget showing total platform metrics (X filings tracked across Y companies, last ingested Z minutes ago). Also useful as a marketing-page counter ('FinRadar tracks 2.4M+ SEC filings across 26K+ securities') and for client-side staleness detection ('last ingestion was 47 minutes ago — show a warning').

**Sample response:**
```json
{
  "total_filings": 2420187,
  "total_insiders": 92418,
  "total_holdings_13f": 348290612,
  "total_tickers": 26080,
  "total_endpoints_documented": 156,
  "last_filing_at": "2026-05-02T20:14:32Z",
  "last_13f_quarter": "2025-12-31",
  "request_id": "req_5pQ9LmN8K2vXwY3z",
  "timestamp": "2026-05-02T20:15:00Z"
}
```

### GET /api/v1/facts

Get system-wide facts.

**Token cost:** 10 tokens per call

**Response fields:**
- `total_filings` (integer): Cumulative count of SEC filings successfully accepted and persisted to the `filings` table since 2000 — covers Forms 3/4/5, 13F-HR/NT, 13D/G, 8-K, 10-K/Q, S-1, 20-F, and ~340 other root form types. Increments roughly +5K/day off-season and +50K/day during 13F deadline windows.
- `last_filing_at` (string): ISO-8601 UTC timestamp of the most recent successful filing acceptance (the moment the filing landed in our DB, NOT the filed_at on EDGAR which is timezone-loose). Lag should be < 60s during ET market hours; values older than ~10 minutes outside the SEC's overnight quiet-window (10pm-6am ET) are an ingestion-pipeline alert.
- `queue_depth` (integer): Live count of accepted-but-not-yet-parsed filings in the Celery `sec_13f` + `sec_filings` queues. Steady-state < 50; values 100-500 indicate filing-season pressure (normal at 10-Q peak); values > 1,000 indicate worker backlog and merit a sec_watchdog inspection.
- `by_form_type` (object): Map of form_type → count for the last 90 days (e.g. `{"4": 28432, "13F-HR": 9617}`). Only forms with non-zero activity in the window appear. Use this to confirm expected magnitudes per form type before kicking off heavy historical queries; sudden zeros on a form type usually indicate a parser regression rather than an SEC issuance pause.
- `as_of` (string): ISO-8601 UTC timestamp the snapshot was generated server-side (cached up to 60 seconds). Treat any consumer-side `now() - as_of > 90s` as stale-cache contention rather than a stale source — re-poll once before alerting.

**Since:** v1.0.0

**Utility:** A lightweight platform health probe that returns the cumulative SEC filing count, the most-recent acceptance timestamp, the live parsing-queue depth, and a per-form-type breakdown of the last 90 days. Operations teams and external status-board integrations use this as a 60-second-cached canonical reference for 'is FinRadar ingesting?' — pair it with `GET /api/v1/status` to also cover service-level health. The 90-day form-type histogram is the cheapest way to confirm Form 4 / 13F-HR / 8-K / 10-K throughput is at expected magnitudes before kicking off heavier per-filing queries.

**Use case:** Dashboard widgets showing total filings processed.

**Sample response:**
```json
{
  "total_filings": 2845129,
  "last_filing_at": "2026-05-01T20:54:12.000Z",
  "queue_depth": 14,
  "by_form_type": {
    "4": 28432,
    "13F-HR": 9617,
    "8-K": 16244,
    "10-K": 4112,
    "10-Q": 12055,
    "13D": 412,
    "13G": 1208
  },
  "as_of": "2026-05-01T20:55:00.000Z"
}
```