Skip to content
/api/v1/sec/filings

List filings with pagination and filtering.

List filings with pagination and filtering. When querying by ticker, if no local filings exist yet, the API automatically backfills the complete filing history from SEC EDGAR (first call may take a few seconds).

5 tokensSince v1.0.0

Why use this

Canonical SEC filings list endpoint — paginated, ticker/CIK/form-type/date-range filterable, and self-healing (auto-backfills from SEC EDGAR's submissions API on first ticker query so you never see an empty result for a real issuer). Returns one row per filing with the SEC accession number, filer CIK + entity name + ticker, the form type (canonical strings: `10-K`, `10-Q`, `8-K`, `4`, `13F-HR`, `13D`, `13G`, `S-1`, `20-F`, `144`, `DEF 14A`, etc. — see [SEC EDGAR's form-type catalog](https://www.sec.gov/forms) for the full list), filing dates, and the document URL set (`primary_link`, `primary_html_url`, full `all_links` array). Pair this with `GET /api/v1/sec/filings/{accession_number}` to drill into a specific filing's documents, with `POST /api/v1/scrapping/search/` for full-text content search across filing bodies, or with `GET /api/v1/sec/filings/stats` for aggregate counts.

Common use case

Building a timeline of filings for a specific company or monitoring all new 8-K filings. Example: GET /api/v1/sec/filings?ticker=XAIR&limit=500 returns all XAIR filings, auto-fetching from EDGAR if needed.

Canonical chronological filings list — paginated, filterable by ticker / CIK / form_type / date-range, and self-healing on first-touch (auto-backfills the full submissions history from SEC EDGAR when no local data exists for a queried ticker). The first call for a fresh ticker may take a few seconds while the auto-backfill runs; subsequent calls hit the local index instantly. Use this as the entry point for any filing-timeline workflow, then drill into a specific filing with GET /api/v1/sec/filings/{accession_number} to fetch the full document URL set, or with GET /api/v1/sec/filings/{accession_number}/html for the primary document body. For aggregate counts use GET /api/v1/sec/filings/stats; for full-text search across filing bodies use POST /api/v1/scrapping/search/. 13F-specific holdings are surfaced separately via GET /api/v1/13f/filer/{cik}/holdings.

Parameters

NameInRequiredDefaultAllowedDescriptionExample
tickerqueryoptional——Company Ticker (e.g. AAPL). Triggers auto-backfill from SEC EDGAR if no local data exists.AAPL
form_typequeryoptional——Filter by Form Type (10-K, 4, 8-K)4
from_datequeryoptional——Start Date (YYYY-MM-DD)2026-01-01
to_datequeryoptional——End Date (YYYY-MM-DD)2026-04-01
sortqueryoptionalfiled_date:desc—Sort order. Format: field:direction. Fields: filed_date, updated_at. Directions: asc, desc. Shorthand 'asc'/'desc' also accepted (defaults to filed_date). Examples: sort=desc, sort=filed_date:ascfiled_at
limitqueryoptional50—Max 500 records20
offsetqueryoptional0—Pagination offset0

Response schema

FieldTypeNullableDescription
statusstringnoAlways `"success"` on 2xx. ApiResponse envelope marker — present on every endpoint that wraps via `ApiResponse.paginated()`. Use to assert the call succeeded before reading `data`.
request_idstringyesPer-request UUID generated server-side. Surface this in support tickets — operations can grep it directly out of nginx + main_api logs to trace the exact request lifecycle (gateway routing, auth resolution, token debit, response).
timestampstringnoISO-8601 UTC timestamp the response was generated server-side (suffix `Z`). Use as the freshness marker — auto-backfill calls that take a few seconds will surface here as a measurable lag from your client-side `Date.now()`.
dataarraynoArray of filing rows matching the query, sorted by `filed_date DESC` by default (newest first; configurable via `sort` param). Empty array when no rows match — never null. One element per filing — see `data[].*` for shape.
data[].idintegernoInternal `sec_filing_entries.id` row ID (auto-increment primary key). Stable across calls but not portable across environments — always join via `accession_number` for cross-environment work.
data[].accession_numberstringnoSEC accession number in the canonical 18-char dashed format `XXXXXXXXXX-YY-NNNNNN` (e.g. `0000320193-25-000123`). Globally unique across EDGAR; the natural primary key for any filing. Pass this to `GET /api/v1/sec/filings/{accession_number}` to retrieve metadata and document URLs.
data[].tickerstringyesResolved ticker from the filer CIK via the `ticker_norm_aliases` lookup. Null when the filer has no public-equity ticker (private funds, individuals filing Form 4, foreign issuers without ADRs, dissolved entities). Multi-class issuers return the primary share class (e.g. BRK-A for Berkshire Hathaway).
data[].form_typestringnoCanonical SEC form type as filed (e.g. `10-K`, `10-Q`, `8-K`, `4`, `13F-HR`, `13F-NT`, `13D`, `13G`, `S-1`, `20-F`, `144`, `DEF 14A`). Amendment variants append `/A` (e.g. `13D/A`, `10-K/A`). NT-prefixed and -NT-suffixed forms (`NT 10-K`, `13F-NT`) appear verbatim — these have no information table to drill into. Reference [SEC EDGAR form types](https://www.sec.gov/forms) for the full catalog.
data[].cikstringyesFiler CIK as a zero-padded 10-character string (e.g. `0000320193` for Apple). Note: SEC EDGAR's submissions API returns the unpadded form; FinRadar normalizes to 10-char padded form everywhere. Stable across decades — same CIK refers to the same legal entity.
data[].entity_namestringyesFiler's legal entity name as registered with SEC (e.g. `Apple Inc.`, `BERKSHIRE HATHAWAY INC`). Casing is whatever EDGAR provides — typically uppercase for institutional filers, mixed-case for issuers. For display, prefer the `company_name` alias which is the same value.
data[].company_namestringyesFrontend-friendly alias of `entity_name`. Same value, kept for backwards compatibility with older client code that queried `company_name`.
data[].rolestringyesRole of the filer in this filing — relevant for insider filings (Form 4) and institutional filings (13F). Null for issuer filings (10-K/10-Q/8-K). Common values: `Reporting Owner`, `Issuer`, `Filer`.
data[].titlestringnoFree-text title from the EDGAR submissions feed (e.g. `8-K - APPLE INC (0000320193) (Filer)`). Useful for full-text search; for structured fields prefer `form_type` + `entity_name`.
data[].summary_htmlstringyesOptional HTML summary block from EDGAR (typically empty on Form 4 and 8-K; populated on 13F-HR with structured holdings summary). Treat as untrusted HTML — sanitize before rendering in a browser.
data[].filing_sizestringyesFiling size as a human-readable string (e.g. `"245 KB"`, `"2.1 MB"`). NOT a numeric byte count — for byte-level work parse the string client-side or fetch the document directly.
data[].filed_datestringyesISO date `YYYY-MM-DD` of the filing's SEC acceptance date in ET (NOT UTC; matches the date EDGAR's index pages show). For intra-day ordering use `updated_at` which carries a full timestamp.
data[].filed_atstringyesFrontend-friendly alias of `filed_date`. Same value, kept for backwards compatibility.
data[].updated_atstringnoISO-8601 UTC timestamp of the last server-side update to this row (e.g. on a backfill refresh). Use as the cursor for incremental sync — sort `updated_at:desc` and persist the max value as your watermark.
data[].primary_linkstringyesCanonical SEC EDGAR URL for the filing's index page (lists all documents in the filing package). Use this as the human-readable link in dashboards.
data[].primary_html_urlstringyesDirect URL of the filing's primary HTML document (the actual 10-K/8-K/13F body, not the index page). For programmatic access use this with `GET /api/v1/sec/document?url=...` or with `GET /api/v1/sec/filings/{accession_number}/html`.
data[].document_filesarrayyesJSON array of structured document descriptors `[{type, document, description, size}, ...]` extracted from the filing's index page. Useful for filtering specific exhibits (e.g. EX-99.1, EX-10.1) before fetching.
data[].data_filesarrayyesJSON array of XBRL/data file descriptors `[{type, document, description, size}, ...]`. Populated on 10-K/10-Q/8-K filings with embedded XBRL; null on filings without XBRL (e.g. older Form 4s).
data[].itemsarrayyesArray of 8-K item codes disclosed in this filing (e.g. `["2.02", "9.01"]` for an earnings-release 8-K). Null on non-8-K forms. Use for material-event surveillance — filter on specific item codes (1.01 = Material Definitive Agreement, 2.02 = Earnings, 5.02 = Officer Change, 8.01 = Other).
data[].period_of_reportstringyesISO `YYYY-MM-DD` period the filing covers (the fiscal-period-end date for 10-K/10-Q, the trade date for Form 4, the report date for 13F-HR). Null for filings without a meaningful period (e.g. some 8-Ks). Differs from `filed_date` — `period_of_report` is the as-of date, `filed_date` is the disclosure date.
data[].sicstringyesStandard Industrial Classification code (4-digit string, e.g. `3674` = Semiconductors). Null when not assigned. For richer industry categorization, join against the Sharadar SF1 industry table via the resolved ticker.
data[].all_linksarrayyesArray of every document URL listed on the filing's index page — exhibits, XBRL data, images, the primary document. Pass any element to `GET /api/v1/sec/document?url=...` to fetch its content.
data[].first_seen_atstringnoISO-8601 UTC timestamp when FinRadar first ingested this filing (typically within seconds of SEC acceptance for filings caught by the RSS poller; longer for backfilled rows). Use for ingest-latency analytics.
data[].last_seen_atstringnoISO-8601 UTC timestamp of the last time the RSS poller observed this filing on EDGAR. Updated on every poll cycle for filings still in the active feed; frozen for older filings.
meta.paginationobjectnoOffset-based pagination metadata: `{total, limit, offset, has_more}`. Use `has_more` as the canonical end-of-iteration signal rather than comparing `data.length` to `limit`.
meta.pagination.totalintegernoExact total count of filings matching the query (full-table count, not just the current page). Computed via a parallel `COUNT(*)` query — reliable for UI pagers but adds ~50-200ms latency on broad queries.
meta.pagination.has_morebooleanno`true` when more pages exist beyond this one (`total > offset + data.length`). Canonical end-of-iteration signal — when `false`, stop paginating.
meta.backfilled_from_edgarbooleanyesPresent and `true` ONLY when this call triggered an auto-backfill from SEC EDGAR (i.e. the ticker had no local data or only recent RSS-captured data). Absent on the typical hot-path call. Use to surface a UX hint ("first call took a moment to fetch full history").
meta.requested_tickerstringyesEcho of the resolved ticker after Phase-53 normalization (e.g. `BRK.A` becomes `BRK-A`). Present only when the request included a `ticker` param.
meta.primary_tickerstringyesCanonical primary share class for the filer (e.g. for Berkshire Hathaway, returns `BRK-A` even if the user queried `BRK.B`). Use to pivot to the multi-class top-of-book.
meta.cikstringyes10-char zero-padded CIK of the resolved ticker. Use as the join key against XBRL, 13F, or insider-filing tables.
meta.companystringyesResolved entity name for the ticker (e.g. `Apple Inc.`). Useful as a display label when the user queried by ticker rather than entity_name.

Sample response

·
  • "status": "success"
  • "request_id": "0f14ed05-3a2e-4b76-9c11-1a7c8b3f6de2"
  • "timestamp": "2026-05-02T16:30:14.122Z"
  • "data":
    ]
  • "meta":
    • "pagination":
    • "requested_ticker": "AAPL"
    • "primary_ticker": "AAPL"
    • "cik": "0000320193"
    • "company": "Apple Inc."
    }
}

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?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).