Skip to content
/api/v1/scrapping/query/

Advanced Boolean Search.

Advanced Boolean Search.

25 tokensSince v1.0.0

Why use this

Advanced filing search using Lucene-syntax boolean queries, compatible with a widely-used commercial SEC-data API format — drop-in for customers migrating from that API'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 the widely-used commercial SEC-data API'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'.

Filing query compatible with a widely-used commercial SEC-data API format — pass a Lucene-style query string and receive paginated filing metadata. Supports the same syntax customers already use on that API (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

NameInRequiredDefaultAllowedDescriptionExample
querybodyrequired——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]`. Quoted and unquoted CIK equality selectors match leading-zero variants of the same company ID: `cik:320193` and `cik:"0000320193"` select the same company. This does not change CIK ranges, merge stored records, or deduplicate existing filing/company association rows. 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 the widely-used commercial SEC-data API's full-text-search endpoint.ticker:AAPL AND formType:10-K
limitbodyoptional50—Maximum filings returned, capped at 50 server-side per page (matches the widely-used commercial SEC-data API'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

FieldTypeNullableDescription
filingsarraynoMatching filing/company association rows; existing duplicates remain separate.
filings[].idstringnoStored filing/company row identifier, serialized as text.
filings[].accessionNostringnoSEC filing accession number.
filings[].cikstringyesCompany identifier in its stored spelling; equality searches match leading-zero variants without rewriting this value.
filings[].tickerstringyesStored ticker, or null when absent.
filings[].formTypestringnoStored SEC form type.
filings[].companyNameLongstringnoStored filing-entry title.
filings[].companyNamestringyesStored company name.
filings[].descriptionstringnoStored filing-entry title, matching companyNameLong.
filings[].linkToFilingDetailsstringyesStored primary HTML URL when present, otherwise the primary link.
filings[].linkToTxtstringyesStored primary link.
filings[].linkToHtmlstringyesStored primary HTML URL, or null.
filings[].linkToXbrlstringyesAssociated filing's XBRL link; empty string if no associated filing exists, possibly null when its link is absent.
filings[].filedAtstringyesStored filing date as YYYY-MM-DD, or null; not an intraday acceptance timestamp.
filings[].periodOfReportstringyesThis existing endpoint repeats filedAt here; it does not retrieve a separate reporting period.
filings[].documentFormatFilesarraynoAssociated filing document rows; empty when none are available.
filings[].documentFormatFiles[].sequencestringyes—
filings[].documentFormatFiles[].sizestringyes—
filings[].documentFormatFiles[].documentUrlstringyes—
filings[].documentFormatFiles[].descriptionstringyes—
filings[].documentFormatFiles[].typestringyes—
filings[].dataFilesarraynoAssociated filing data-file rows; empty when none are available.
filings[].dataFiles[].sequencestringyes—
filings[].dataFiles[].sizestringyes—
filings[].dataFiles[].documentUrlstringyes—
filings[].dataFiles[].descriptionstringyes—
filings[].dataFiles[].typestringyes—
filings[].entitiesarraynoThe company association represented by this returned row.
filings[].entities[].cikstringyes—
filings[].entities[].companyNamestringyes—
filings[].entities[].typestringno—
filings[].seriesAndClassesContractsInformationarraynoEmpty array in the existing response.
totalobjectnoMatching row count before limit and offset; not a distinct-filing or transaction count.
total.valueintegerno—
total.relationstringno—

Sample response

·
  • "filings":
    ]
  • "total":
    • "value": 1
    • "relation": "eq"
    }
}

Errors

StatusLabelDescription
200OKRequest succeeded.
400Bad RequestInvalid query, body, or path parameter.
401UnauthorizedMissing or invalid Authorization header / api_Token.
402Payment RequiredInsufficient token balance for this call. Top up
429Too Many RequestsRate limit exceeded for your tier (see /pricing for tier limits). Tier limits
500Server ErrorUnexpected server-side failure. Retry with backoff; report if persistent.

Code samples

curl -X POST "https://api.finradar.ai/api/v1/scrapping/query/" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "query": "ticker:AAPL AND formType:10-K",
  "limit": "20"
}'

Generate an API key in /account/credentials to run live queries (literal YOUR_API_KEY placeholder shown until then).

Try it

Related endpoints

/api/v1/scrapping/search/25 tokens/api/v1/scrapping/extractor25 tokens/api/v1/sec/filings5 tokens/api/v1/scrapping/xbrl25 tokens