Skip to content

GET /v3/search

Full-text search over every document v3 holds (spec §6.1). q uses the SEC Blast query syntax (syntax=edgar reads it as EDGAR full-text search does); the structured parameters are AND-ed with it, and EDGAR's own URL parameters (forms, ciks, startdt, enddt, dateRange, entityName, locationCode, locationType, category, page) are accepted, so an EDGAR search URL replays. Rows are documents (group=document) or filings with their best documents (group=filing); each document carries url, the route of its stored bytes. Snippet offsets are characters of the text that /v3/filings/{accession}/documents/{document}/text returns. Page with cursor (next_cursor). fields= trims the rows, never the envelope. Query errors are 400 with position and length; 503 search_busy, search_timeout and ticker_resolution_unavailable carry Retry-After.

API key: required. See Authentication.

Group: Full-text search

Parameters

NameInTypeRequiredDefaultDescription
qquerystringnoQuery (at most 1,000 characters); empty lists by filters only.
syntaxquerystringnosbQuery syntax. One of: sb, edgar.
matchquerystringnoexactTerm matching. One of: exact, stem.
formsquerycomma-separated list of stringnoRoot form types (EDGAR alias): 10-K matches 10-K, 10-K/A, 10-K405. A leading - excludes (forms=-3,-4,-5).
form_typesquerycomma-separated list of stringnoExact form types, for example 10-K/A. A leading - excludes.
form_familiesquerycomma-separated list of stringnoRoot form types. A leading - excludes.
doctypesquerycomma-separated list of stringnoDocument types; a * suffix matches a prefix (EX-10*).
ciksquerycomma-separated list of stringnoCIKs (1 to 10 digits each, at most 1,024).
tickersquerycomma-separated list of stringnoTickers (at most 64); sb_search resolves them to CIKs.
sicsquerycomma-separated list of stringnoSIC codes; a * suffix matches a prefix (73*).
statesquerycomma-separated list of stringnoBusiness-address state codes.
inc_statesquerycomma-separated list of stringnoState-of-incorporation codes.
filed_fromquerydate (YYYY-MM-DD)noEarliest filing date, YYYY-MM-DD.
filed_toquerydate (YYYY-MM-DD)noLatest filing date, YYYY-MM-DD.
startdtquerydate (YYYY-MM-DD)noEDGAR alias of filed_from.
enddtquerydate (YYYY-MM-DD)noEDGAR alias of filed_to.
dateRangequerystringnoall applies no lower bound and is a 400 with startdt/filed_from; 10y, 5y, 1y, 30d set filed_from relative to today and are also a 400 with startdt/filed_from; custom (default) uses startdt/filed_from. One of: all, 10y, 5y, 1y, 30d, custom.
accepted_toquerystringnoLatest acceptance time: YYYY-MM-DDTHH:MM:SSZ, or a date meaning the end of that UTC day.
as_ofquerystringnoAlias of accepted_to.
statusquerycomma-separated list of stringnoFiling statuses: provisional, final, deleted (SEC deleted the filing; its documents stay searchable). Default: every status, deleted filings included.
primary_onlyquerystringnoautoPrimary documents only. auto: true when q is empty, else false. One of: true, false, auto.
entityNamequerystringnoEDGAR entity name; becomes a name phrase filter (approximate).
locationCodequerystringnoEDGAR state code; becomes states, or inc_states when locationType=incorporated.
locationTypequerystringnoEDGAR: located or incorporated; consumed by locationCode.
categoryquerystringnoAccepted for EDGAR URL replay; ignored.
pagequerystringnoAccepted for EDGAR URL replay; ignored (use cursor).
groupquerystringnodocumentResult unit. One of: document, filing.
collapsequerystringnofalseCollapse near-duplicate results. One of: true, false.
sortquerystringnoSort key; default relevance when q has a positive term, else date. One of: relevance, date, accepted.
orderquerystringnodescSort order. One of: desc, asc.
limitqueryintegerno20Page size, 1 to 100.
cursorquerystringnoOpaque cursor from next_cursor.
fromqueryintegerno0Offset, 0 to 10,000 (compatibility; use cursor beyond).
facetsquerycomma-separated list of stringnoFacets to compute: form, year, sic, state.
facet_sizequeryintegerno30Buckets per facet, 1 to 100.
snippetsqueryintegerno1Snippets per document, 0 to 5.
snippet_charsqueryintegerno240Snippet length, 80 to 600.
docs_per_filingqueryintegerno3Documents shown per filing, 1 to 10.
fieldsquerycomma-separated list of stringnoHit members to keep in each row.
totalsquerystringnotrueCompute totals. One of: true, false.

Responses

StatusBodyDescription
200SearchResults (application/json)OK
400Problem (application/problem+json)Invalid or unknown parameter, or a query error (invalid_query, query_too_complex, prefix_too_broad, negative_only_query, unsupported_operator, invalid_cursor); query errors carry position and length (characters of q).
401Problem (application/problem+json)Missing, invalid or inactive API key (code unauthorized), or a refused access token (code invalid_token: malformed, unknown key, bad signature, expired, wrong issuer or audience, revoked grant). WWW-Authenticate names the protected-resource metadata (RFC 9728).
503Problem (application/problem+json)Full-text search cannot answer now: search_unavailable (sb_search unreachable or not configured), search_busy (its queue is full), search_timeout (the query hit its time budget), ticker_resolution_unavailable; or the database is unavailable. Retry after the Retry-After delay when one is given.
defaultProblem (application/problem+json)Any other error (405, 500, 504).

Response body

A 200 carries a SearchResults object.

FieldTypeRequiredDescription
dataarray of SearchHityes
facetsSearchFacetsno
has_morebooleanyes
indexSearchIndexInfoyes
next_cursorstring | nullyesPass back as cursor with the same query, filters, sort and group. Null when nothing follows, and always null with from > 0.
resolvedobjectyes{tickers: {TICKER: [cik, ...]}}: how tickers were resolved.
resolved.tickersobjectno
took_msintegeryes
totalSearchTotalsyes
warningsarray of SearchWarningyes

Example request

Shell
curl -sS -H "Authorization: Bearer $SECBLAST_API_KEY" \
  'https://api.secblast.com/v3/search'

Open this route in the console

Previous: GET /v3/filings/{accession}/documents/{document}/text · Next: GET /v3/search/parse

Markdown version: /docs/reference/get-search.md