Skip to content
/api/v1/sec/filings/stats

Aggregate counts of filings by form type, filer, or date range.

Aggregate counts of filings by form type, filer, or date range. Returns counts only — does not return individual filings.

5 tokensSince v1.0.0

Why use this

Aggregate-counts endpoint over the local filings index — total filing count, top-10 form types by count, latest filing date observed. The right surface for: dashboard headline stats ("X filings indexed; latest 2026-05-02"), monitoring panels checking ingest freshness (`latest_filing_date` should never be more than 1-2 days behind today during active hours), the "Did our RSS poller break?" canary. Returns aggregates only — no per-filing rows. For filtered counts (e.g. "how many 8-Ks did Apple file in 2025?") combine `GET /api/v1/sec/filings?ticker=...&form_type=...&from_date=...` with a `count`-only query against the `meta.pagination.total` field.

Headline aggregate stats over the local filings index — total filing count, top-10 form types by count, latest filing date observed. The right endpoint for dashboard widgets ("X filings indexed"), ingest-freshness canaries (latest_filing_date lag), and order-of-magnitude form-type distribution analysis. Returns aggregates only — no individual filing rows. For per-form drill-down use GET /api/v1/sec/forms/{form_type}; for filtered counts (e.g. "how many 8-Ks from AAPL in 2025?") use GET /api/v1/sec/filings?ticker=AAPL&form_type=8-K&from_date=... and read meta.pagination.total. For full distinct-entity catalog use GET /api/v1/sec/entities.

Response schema

FieldTypeNullableDescription
statusstringnoAlways `"success"` on 2xx. ApiResponse envelope marker — wraps via `ApiResponse.success()`.
request_idstringyesPer-request UUID generated server-side.
timestampstringnoISO-8601 UTC timestamp the response was generated server-side.
dataobjectnoStats envelope — see `data.*` for fields. All counts reflect the local index, not SEC's universe (recently-onboarded form types may show low counts here even though they're widely filed).
data.total_entriesintegernoTotal count of filings in the local `sec_filing_entries` index (all form types, all filers, all dates). Computed via `COUNT(*)` — typically 30M+ rows in the production index.
data.top_form_typesarraynoTop 10 form types by `filing_count`, sorted descending. Always 10 elements (or fewer if the index has fewer distinct form types — extremely unlikely in production). Mirrors the top of `GET /api/v1/sec/forms`'s response.
data.top_form_types[].form_typestringnoCanonical SEC form type (e.g. `4`, `13F-HR`, `8-K`).
data.top_form_types[].countintegernoFiling count for this form type. Typically dominated by Form 4 (insider transactions, ~8M+) and 13F-HR (institutional holdings, ~400K).
data.latest_filing_datestringyesISO date `YYYY-MM-DD` of the most recent filing in the local index (`MAX(filed_date)`). Use as the freshness canary — should never be more than 1-2 days behind today during active business hours; gaps suggest the RSS poller is stalled. Null only when the index is empty (initial setup).
data.timestampstringnoISO-8601 UTC timestamp the stats query ran server-side. Inside `data` rather than the envelope's `timestamp` — useful for stats-snapshot caching.

Sample response

·
  • "status": "success"
  • "request_id": "0f14ed05-3a2e-4b76-9c11-1a7c8b3f6de2"
  • "timestamp": "2026-05-02T16:30:14.122Z"
  • "data":
    • "total_entries": 32184529
    • "top_form_types":
    • "latest_filing_date": "2026-05-02"
    • "timestamp": "2026-05-02T16:30:14.122000"
    }
}

Errors

StatusLabelDescription
200OKRequest succeeded.
400Bad RequestInvalid query, body, or path parameter.
401UnauthorizedMissing or invalid Authorization header / api_Token.
402Payment RequiredInsufficient token balance for this call. Top up
429Too Many RequestsRate limit exceeded for your tier (see /pricing for tier limits). Tier limits
500Server ErrorUnexpected server-side failure. Retry with backoff; report if persistent.

Code samples

curl "https://api.finradar.ai/api/v1/sec/filings/stats?api_Token=YOUR_API_KEY" \
  -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).