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
| Name | In | Type | Required | Default | Description |
|---|---|---|---|---|---|
q | query | string | no | Query (at most 1,000 characters); empty lists by filters only. | |
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). | |
group | query | string | no | document | Result unit. One of: document, filing. |
collapse | query | string | no | false | Collapse near-duplicate results. One of: true, false. |
sort | query | string | no | Sort key; default relevance when q has a positive term, else date. One of: relevance, date, accepted. | |
order | query | string | no | desc | Sort order. One of: desc, asc. |
limit | query | integer | no | 20 | Page size, 1 to 100. |
cursor | query | string | no | Opaque cursor from next_cursor. | |
from | query | integer | no | 0 | Offset, 0 to 10,000 (compatibility; use cursor beyond). |
facets | query | comma-separated list of string | no | Facets to compute: form, year, sic, state. | |
facet_size | query | integer | no | 30 | Buckets per facet, 1 to 100. |
snippets | query | integer | no | 1 | Snippets per document, 0 to 5. |
snippet_chars | query | integer | no | 240 | Snippet length, 80 to 600. |
docs_per_filing | query | integer | no | 3 | Documents shown per filing, 1 to 10. |
fields | query | comma-separated list of string | no | Hit members to keep in each row. | |
totals | query | string | no | true | Compute totals. One of: true, false. |
Responses
| Status | Body | Description |
|---|---|---|
200 | SearchResults (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 SearchResults object.
| Field | Type | Required | Description |
|---|---|---|---|
data | array of SearchHit | yes | |
facets | SearchFacets | no | |
has_more | boolean | yes | |
index | SearchIndexInfo | yes | |
next_cursor | string | null | yes | Pass back as cursor with the same query, filters, sort and group. Null when nothing follows, and always null with from > 0. |
resolved | object | yes | {tickers: {TICKER: [cik, ...]}}: how tickers were resolved. |
resolved.tickers | object | no | |
took_ms | integer | yes | |
total | SearchTotals | yes | |
warnings | array of SearchWarning | yes |
Example request
curl -sS -H "Authorization: Bearer $SECBLAST_API_KEY" \
'https://api.secblast.com/v3/search'Open this route in the console
More in Full-text search
Previous: GET /v3/filings/{accession}/documents/{document}/text · Next: GET /v3/search/parse
Markdown version: /docs/reference/get-search.md