Skip to content

GET /v3/search/parse

How a query is read, without running it: the normalised query, its tree, the EDGAR reading beside the default one, prefix expansions, the structured filters after alias mapping and ticker resolution, and the index years it would touch. Errors as /v3/search.

API key: required. See Authentication.

Group: Full-text search

Parameters

NameInTypeRequiredDefaultDescription
qquerystringnoQuery (at most 1,000 characters).
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).

Responses

StatusBodyDescription
200SearchParse (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 SearchParse object.

FieldTypeRequiredDescription
astobject | nullnoThe query tree under the requested syntax: sexpr and tree.
differsbooleannoThe two readings differ.
edgarobjectnoThe EDGAR reading: ast, echo (the query EDGAR would build) and error when it does not parse.
filtersobjectnoThe structured filters after alias mapping and ticker resolution.
matchstringnoOne of: exact, stem.
normalizedstringnoThe normalised query.
prefixesarray of objectno
prefixes[].cappedbooleanno
prefixes[].expansionsintegerno
prefixes[].in_spanbooleannoInside NEAR or a phrase (capped at 1,024 expansions).
prefixes[].prefixstringno
prefixes[].toparray of array of anynoUp to 20 [term, document frequency] pairs.
resolvedobjectno{tickers: {TICKER: [cik, ...]}}.
shardsarray of integernoThe index years the query would search.
syntaxstringnoOne of: sb, edgar.
warningsarray of SearchWarningno

Example request

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

Open this route in the console

Previous: GET /v3/search · Next: GET /v3/search/status

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