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
| Name | In | Type | Required | Default | Description |
|---|---|---|---|---|---|
q | query | string | no | Query (at most 1,000 characters). | |
syntax | query | string | no | sb | Query syntax. One of: sb, edgar. |
match | query | string | no | exact | Term matching. One of: exact, stem. |
forms | query | comma-separated list of string | no | Root form types (EDGAR alias): 10-K matches 10-K, 10-K/A, 10-K405. A leading - excludes (forms=-3,-4,-5). | |
form_types | query | comma-separated list of string | no | Exact form types, for example 10-K/A. A leading - excludes. | |
form_families | query | comma-separated list of string | no | Root form types. A leading - excludes. | |
doctypes | query | comma-separated list of string | no | Document types; a * suffix matches a prefix (EX-10*). | |
ciks | query | comma-separated list of string | no | CIKs (1 to 10 digits each, at most 1,024). | |
tickers | query | comma-separated list of string | no | Tickers (at most 64); sb_search resolves them to CIKs. | |
sics | query | comma-separated list of string | no | SIC codes; a * suffix matches a prefix (73*). | |
states | query | comma-separated list of string | no | Business-address state codes. | |
inc_states | query | comma-separated list of string | no | State-of-incorporation codes. | |
filed_from | query | date (YYYY-MM-DD) | no | Earliest filing date, YYYY-MM-DD. | |
filed_to | query | date (YYYY-MM-DD) | no | Latest filing date, YYYY-MM-DD. | |
startdt | query | date (YYYY-MM-DD) | no | EDGAR alias of filed_from. | |
enddt | query | date (YYYY-MM-DD) | no | EDGAR alias of filed_to. | |
dateRange | query | string | no | all 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_to | query | string | no | Latest acceptance time: YYYY-MM-DDTHH:MM:SSZ, or a date meaning the end of that UTC day. | |
as_of | query | string | no | Alias of accepted_to. | |
status | query | comma-separated list of string | no | Filing statuses: provisional, final, deleted (SEC deleted the filing; its documents stay searchable). Default: every status, deleted filings included. | |
primary_only | query | string | no | auto | Primary documents only. auto: true when q is empty, else false. One of: true, false, auto. |
entityName | query | string | no | EDGAR entity name; becomes a name phrase filter (approximate). | |
locationCode | query | string | no | EDGAR state code; becomes states, or inc_states when locationType=incorporated. | |
locationType | query | string | no | EDGAR: located or incorporated; consumed by locationCode. | |
category | query | string | no | Accepted for EDGAR URL replay; ignored. | |
page | query | string | no | Accepted for EDGAR URL replay; ignored (use cursor). |
Responses
| Status | Body | Description |
|---|---|---|
200 | SearchParse (application/json) | OK |
400 | Problem (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). |
401 | Problem (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). |
503 | Problem (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. |
default | Problem (application/problem+json) | Any other error (405, 500, 504). |
Response body
A 200 carries a SearchParse object.
| Field | Type | Required | Description |
|---|---|---|---|
ast | object | null | no | The query tree under the requested syntax: sexpr and tree. |
differs | boolean | no | The two readings differ. |
edgar | object | no | The EDGAR reading: ast, echo (the query EDGAR would build) and error when it does not parse. |
filters | object | no | The structured filters after alias mapping and ticker resolution. |
match | string | no | One of: exact, stem. |
normalized | string | no | The normalised query. |
prefixes | array of object | no | |
prefixes[].capped | boolean | no | |
prefixes[].expansions | integer | no | |
prefixes[].in_span | boolean | no | Inside NEAR or a phrase (capped at 1,024 expansions). |
prefixes[].prefix | string | no | |
prefixes[].top | array of array of any | no | Up to 20 [term, document frequency] pairs. |
resolved | object | no | {tickers: {TICKER: [cik, ...]}}. |
shards | array of integer | no | The index years the query would search. |
syntax | string | no | One of: sb, edgar. |
warnings | array of SearchWarning | no |
Example request
curl -sS -H "Authorization: Bearer $SECBLAST_API_KEY" \
'https://api.secblast.com/v3/search/parse'Open this route in the console
More in Full-text search
Previous: GET /v3/search · Next: GET /v3/search/status
Markdown version: /docs/reference/get-search-parse.md