# 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](https://www.secblast.com/docs/authentication).

**Group:** [Full-text search](https://www.secblast.com/docs/reference#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](https://www.secblast.com/docs/reference/schemas#schema-searchresults) (`application/json`) | OK |
| `400` | [Problem](https://www.secblast.com/docs/reference/schemas#schema-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](https://www.secblast.com/docs/reference/schemas#schema-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](https://www.secblast.com/docs/reference/schemas#schema-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](https://www.secblast.com/docs/reference/schemas#schema-problem) (`application/problem+json`) | Any other error (405, 500, 504). |

## Response body

A `200` carries a [SearchResults](https://www.secblast.com/docs/reference/schemas#schema-searchresults) object.

| Field | Type | Required | Description |
|---|---|---|---|
| `data` | array of [SearchHit](https://www.secblast.com/docs/reference/schemas#schema-searchhit) | yes |   |
| `facets` | [SearchFacets](https://www.secblast.com/docs/reference/schemas#schema-searchfacets) | no |   |
| `has_more` | boolean | yes |   |
| `index` | [SearchIndexInfo](https://www.secblast.com/docs/reference/schemas#schema-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](https://www.secblast.com/docs/reference/schemas#schema-searchtotals) | yes |   |
| `warnings` | array of [SearchWarning](https://www.secblast.com/docs/reference/schemas#schema-searchwarning) | yes |   |

## Example request

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

[Open this route in the console](https://www.secblast.com/console#get-v3-search)

## More in Full-text search

Previous: [`GET /v3/filings/{accession}/documents/{document}/text`](https://www.secblast.com/docs/reference/get-filings-accession-documents-document-text) · Next: [`GET /v3/search/parse`](https://www.secblast.com/docs/reference/get-search-parse)
