/api/v1/scrapping/query/Advanced Boolean Search.
Advanced Boolean Search.
25 tokensSince v1.0.0
Why use this
sec-api.io-compatible advanced filing search using Lucene-syntax boolean queries — drop-in for customers migrating from sec-api.io's `/full-text-search` query endpoint. Supports field-scoped filters (`ticker:`, `formType:`, `cik:`, `filedAt:[from TO to]`), boolean operators (`AND`/`OR`/`NOT`), wildcards (`tesla*`), and grouping (`(formType:10-K OR formType:10-Q) AND ticker:AAPL`). The single most powerful metadata-query endpoint in the FinRadar surface — analyst pipelines that need 'all 10-Ks from S&P 500 issuers in 2025' in one shot. Returns paginated filing metadata in sec-api.io's exact response shape (`filings[]` + `total: {value, relation}`). For full-text inside filing exhibits use `POST /api/v1/scrapping/search/`; for raw row-shaped reads use `GET /api/v1/sec/filings`.
Common use case
Precise filtering: 'Give me all 10-Ks from Apple or Microsoft filed in 2023'.
sec-api.io-compatible filing query — pass a Lucene-style query string and receive paginated filing metadata. Supports the same syntax customers already use on sec-api.io (e.g. formType:"10-K" AND filedAt:[2025-01-01 TO 2025-12-31]). For raw filing-row reads use GET /api/v1/sec/filings; for full-text inside filing exhibits use POST /api/v1/scrapping/search/ which scans extracted text rather than metadata.
Parameters
| Name | In | Required | Default | Allowed | Description | Example |
|---|---|---|---|---|---|---|
| query | body | required | — | — | Lucene-style query string. Field-scoped: `ticker:AAPL`, `formType:"10-K"` (quote multi-word values), `cik:0000320193`, `filedAt:[2025-01-01 TO 2025-12-31]`. Operators: `AND`, `OR`, `NOT`. Wildcards: `tesla*`, `apple?`. Grouping: `(formType:10-K OR formType:10-Q) AND ticker:AAPL`. Bare-word queries match against issuer.name. Identical syntax to sec-api.io's full-text-search endpoint. | ticker:AAPL AND formType:10-K |
| limit | body | optional | 50 | — | Maximum filings returned, capped at 50 server-side per page (matches sec-api.io's per-page cap). For deeper pagination use the `from` field if your client supports it; for full backfills, prefer date-range chunking via the `query.filedAt:[A TO B]` syntax. | 20 |
Response schema
| Field | Type | Nullable | Description |
|---|---|---|---|
| filings | array | no | Array of filings matching the query, in sec-api.io's exact response shape. Sorted by `filedAt DESC` (newest first). Empty array on no match — never null. Compatible with existing client code that already parses sec-api.io responses. |
| filings[].accessionNo | string | no | SEC accession number in canonical `XXXXXXXXXX-YY-NNNNNN` format. Matches sec-api.io's `accessionNo` field naming. Pass to `GET /api/v1/sec/filings/{accession_number}` to drill into the filing's documents in FinRadar's flatter shape. |
| filings[].cik | string | no | Filer CIK as a 10-character zero-padded string. The same CIK always refers to the same legal entity across decades — a stable join key against EDGAR submissions, our `filings` table, and Sharadar SF1. |
| filings[].ticker | string | yes | Ticker resolved from the filer CIK via the `ticker_norm_aliases` lookup. Null when the filer has no public-equity ticker (private funds, individuals, foreign issuers without ADRs, dissolved entities). Multi-class issuers return the primary share class. |
| filings[].formType | string | no | Canonical SEC form type (e.g. `10-K`, `10-Q`, `8-K`, `4`, `13F-HR`, `S-1`, `20-F`). Amendment variants append `/A`. NT-prefixed and -NT-suffixed forms (e.g. `NT 10-K`, `13F-NT`) appear verbatim — these have no information table. |
| filings[].filedAt | string | no | ISO-8601 UTC timestamp of the filing's SEC acceptance moment. Matches sec-api.io's `filedAt` field shape (full timestamp, NOT just the date). |
| filings[].periodOfReport | string | yes | ISO `YYYY-MM-DD` period the filing covers (the fiscal-period-end-date for 10-K/10-Q, the trade date for Form 4, etc.). Null for filings that don't have a meaningful period (e.g. some 8-Ks, S-1 initial registrations). Differs from `filedAt` — `periodOfReport` is the as-of date, `filedAt` is the disclosure date. |
| filings[].linkToFilingDetails | string | no | Canonical SEC EDGAR URL for the filing's index page (lists all documents in the filing package). Use as the human-readable link in dashboards; for programmatic document access use the `/html` companion endpoints which return parsed content. |
| total | object | no | sec-api.io-compatible total-hits block: `{ value: integer, relation: 'eq' | 'gte' }`. The deep-pagination cap fires at 10000 hits — beyond that, switch to date-range chunking (`filedAt:[A TO B]`) since pagination cannot reach further. |
| total.value | integer | no | Total hit count for the full query. Exact when `relation='eq'`; lower-bound when `relation='gte'` (i.e. 'at least this many; the deep-pagination cap was reached'). |
| total.relation | string | no | `eq` = exact total; `gte` = the deep-pagination cap was hit (only triggers when matching > 10000 filings). Use to detect when you need to switch to date-range chunking for full enumeration. |
Sample response
·
- "filings":
- "total":
- "value": 1
- "relation": "eq"
Errors
| Status | Label | Description |
|---|---|---|
| 200 | OK | Request succeeded. |
| 400 | Bad Request | Invalid query, body, or path parameter. |
| 401 | Unauthorized | Missing or invalid Authorization header / api_Token. |
| 402 | Payment Required | Insufficient token balance for this call. Top up |
| 429 | Too Many Requests | Rate limit exceeded for your tier (see /pricing for tier limits). Tier limits |
| 500 | Server Error | Unexpected server-side failure. Retry with backoff; report if persistent. |
Code samples
curl -X POST "https://api.finradar.ai/api/v1/scrapping/query/?api_Token=YOUR_API_KEY" \
-H "Authorization: Bearer YOUR_JWT_TOKEN"Generate an API key in /account/credentials to run live queries (literal YOUR_API_KEY placeholder shown until then).