---
title: "Search and list filings"
method: GET
path: "/edgar/filings"
tags: ["EDGAR"]
---

# Search and list filings

`GET /edgar/filings`

## Request

- Base URL: `https://api.signal8.ai/api/v1/public`
- URL: `https://api.signal8.ai/api/v1/public/edgar/filings`
- Auth: API key in header `X-Api-Key`

Search and list SEC filings from Signal8's archive (EDGAR filings in the
archive's held range — see `archiveFrom` in each response; currently
from late 2021, expanding back to 2016 as the history backfill fills
in. Older filings may be absent, so an empty result is not proof of
absence). Filter by CIK, form type, date range, 8-K item
codes and excluded forms; optionally full-text `q` (websearch syntax:
unquoted words must ALL appear, "quoted phrase", OR, -exclude).

**Company filters** (`minMarketCap` … `recentIpo`) use the same
contract as signal8.ai/sec-filings and are served from the archive
only: issuer-filed forms only (Form 4 / 144 / SCHEDULE 13D/G are
dropped and listed in `companyFilter.droppedForms` — unless
`companyFilter.subjectMatch` is true, when they are searched by the
company they are about; with no
`formTypes` the default is 10-K, 10-Q, 8-K, S-1, S-3, DEF 14A, 20-F,
40-F, 6-K); companies with no measured value for a filter are EXCLUDED
and counted in `companyFilter.unknown`; unknown values are a 400 that
lists the valid names; an archive that cannot answer returns 503/422
`COMPANY_FILTER_NOT_APPLIED` with a `reason` — never unfiltered rows.
Company-filtered requests are cursor-paged (`page` > 1 is a 400) and
cannot be combined with `aiAnalysed`, `hasRofr`, `extractionTypes`,
`bodyStored`, `acceptedFrom` or `acceptedTo`.

**Credit cost: 5**

## Query parameters

- `ciks` string
- `page` integer
- `pageSize` integer
- `formTypes` string
- `dateFrom` string
- `dateTo` string
- `aiAnalysed` string
- `hasRofr` string
- `extractionTypes` string
- `q` string
- `sort` string
- `match` string
- `facets` boolean
- `understand` boolean
- `autocorrect` boolean
- `section` string
- `exhibitTypes` string
- `matchedSections` boolean
- `cursor` string
- `items` string
- `excludeForms` string
- `bodyStored` boolean
- `acceptedFrom` string
- `acceptedTo` string
- `minMarketCap` number
- `maxMarketCap` number
- `minFloat` number
- `maxFloat` number
- `minPrice` number
- `maxPrice` number
- `sectors` string
- `industries` string
- `exchanges` string
- `companyTypes` string
- `foreignIssuer` boolean
- `recentIpo` boolean

## Response `200`

Paginated list of filings. `data` is the row array; `pagination`
carries `total`, `totalRelation` ('gte' when the exact count was
cut at 10,000), `totalEstimate` ("about N" beside a 'gte' total,
absent when not estimated), `hasMore` and `nextCursor`. Rows
include `id` (the filingId), `acceptedAt` (null on
archive-backfilled rows), `primaryDocument`, `bodyStored`,
`filerCiks`, `itemNumbers`, and — with `q`, unfiltered only —
`rank` and `snippet {text, matchStart, matchLength, matchCount}`.
`source` is `archive`; `appliedFilters` names the optional filters
applied. On an empty first page of a text search, `searchIndex`
is passed through: only `searchIndex.complete: true` makes the zero
definitive, otherwise `notes` says so.

Every response carries `archiveFrom` (YYYY-MM-DD — the archive
holds only a scatter of filings before it) and
`rangeStartsBeforeArchive`. A range with no `dateFrom` (and no
`acceptedFrom`), or one starting before `archiveFrom`, is NEVER
definitive: `searchIndex` is `complete: false` with
`reason: "outside_held_range"` and `heldFrom`, and `notes` says
absence before `archiveFrom` is not evidence a filing was never
filed — check SEC EDGAR for earlier periods.

With `q`, `meta` (when the archive states it) reports `engine`
(`postgres` | `opensearch`), `matchMode` — the word matching
APPLIED, which can be `stemmed` although `exact` was requested —
and `matchModeFallbackReason` when the two differ. `meta` is
absent when not stated; absence is not a claim about either.

`meta.understanding` (with `q`, when stated) describes how the
archive read the query: `tickers`, `companies [{cik, name}]`,
`forms`, `items`, `years`, `synonyms [{term, expandedTo}]`,
`proximity`, `wildcard`, `strippedQuery` — each key present only
when it applies. With `facets=true`, top-level `facets { forms,
years, items }` (each `[{value, count}]`) counts the whole result
set; absent when not measured. Rows may carry `items` (8-K item
codes), `exhibitTypes` and `primaryDocType` when the archive
states them.

Wave 3 (section search): with `section`, `meta.sections` is the
restriction APPLIED; `meta.unsupported [{param, reason}]` lists
params that were NOT applied (`section` on an index without
sections, `exhibitTypes` the rows could not prove) — a note in
`notes` says so too. Text rows may carry `matchedSections`
(absent ⇒ not measured). With `facets=true`, `facets.sections` /
`facets.exhibitTypes` appear when measured.

With `sort=relevance`, page 1 shows at most `maxPerCompany`
filings per company; `meta.diversity { maxPerCompany, hidden:
[{cik, count}] }` names the companies with more. Page on with
`nextCursor` (page-number paging is not diversified).

Company-filtered responses add `ticker` to each row (no
`snippet`), `companyFilter { matchedCompanies, searchedCompanies,
unknown, foreignEvidenceSince, forms, formsDefaulted, droppedForms,
issuerFiledFormsOnly }`, `archiveFrom`, and `notes`.

- object

## Other responses

- `400`: Invalid request parameters
- `401`: Missing or invalid API key
- `402`: Not enough credits for this request
- `422`: A company filter cannot be applied to this request (e.g. only third-party forms requested); `error.code` COMPANY_FILTER_NOT_APPLIED, `error.reason` / `error.details.reason` name why.
- `429`: Rate limit exceeded
- `503`: The archive cannot answer a company-filtered request right now (coverage gap, stale live ingest, unconfirmed empty text result, lookup failure). `error.code` COMPANY_FILTER_NOT_APPLIED with a `reason`; `Retry-After` is set. EDGAR cannot apply company filters, so there is no unfiltered fallback.

---

[API](https://skmtc.dev/signal8/apis/signal8-public-api.md) · [All operations](https://skmtc.dev/signal8/apis/signal8-public-api/llms.txt) · [OpenAPI document](https://skmtc.dev/signal8/apis/signal8-public-api/revisions/5a18ae8d6d58?raw)