/insider-module/api/insiders/querySEC-API compatible filing query.
SEC-API compatible filing query. Returns structured nested JSON — a top-level `{ total, transactions }` object where each `transactions[]` entry is a whole filing (issuer, reportingOwner, nonDerivativeTable, derivativeTable, footnotes).
10 tokensSince v1.4.0
Why use this
Drop-in migration target for customers moving off sec-api.io: accepts a Lucene-style query string (e.g. `ticker:TSLA AND formType:4 AND filedAt:[2026-01-01 TO 2026-04-01]`) and returns SEC-API-shaped nested JSON. The response is `{ total: { value, relation }, transactions: [...] }` where each entry is a filing — issuer block, single reportingOwner object, nonDerivativeTable / derivativeTable each with nested transactions + holdings (securityTitle / coding / amounts / postTransactionAmounts / ownershipNature). The shape is compatible with sec-api.io's `/insider-trading` query endpoint, so existing client code that parses sec-api.io responses Just Works. For lighter row-shaped queries that integrate better with SQL/relational tooling, prefer the flatter `/transactions/search` endpoint.
Common use case
Fetching structured Form 4 filings for programmatic analysis — each filing returns the reporting owner, non-derivative/derivative tables with nested amounts, ownership details, and footnotes.
sec-api.io-compatible Form 4 query interface — accepts a Lucene-style query string and returns SEC-API-shaped nested JSON. The top-level shape is { total, transactions } where each transactions[] entry is a whole FILING (one filing → one entry, with reportingOwner / nonDerivativeTable / derivativeTable / footnotes nested). Provided as a drop-in migration target so customers leaving sec-api.io can switch with minimal client changes. For lighter row-shaped queries that integrate better with relational tooling, prefer GET /insider-module/api/insiders/transactions/search.
Parameters
| Name | In | Required | Default | Allowed | Description | Example |
|---|---|---|---|---|---|---|
| query | body | required | — | — | Lucene-style query string in sec-api.io syntax. Supported fields: `ticker`, `formType` (3, 4, 5, 4/A, etc.), `cik`, `accessionNo`, `filedAt` (ISO date or `[from TO to]` range), `issuer.name`, `reporters.name`. Boolean operators: `AND`, `OR`, `NOT`. Examples: `ticker:TSLA AND formType:4`, `formType:4 AND filedAt:[2026-01-01 TO 2026-04-01]`. Bare-word queries (e.g. `apple`) match against issuer.name + reporters.name. | ticker:AAPL AND formType:4 |
| from | body | optional | 0 | — | Zero-based pagination offset (NOT a date — despite the name overlap with sec-api.io's date-range syntax). Increment by `size` to walk pages: `from=0` → page 1, `from=10` → page 2 (when `size=10`). Capped at 10000 server-side; for deeper backfill use date-range chunking via the `query` field. | 0 |
| size | body | optional | 50 | — | Results per page (1–10000). Each row carries a heavy nested sec-api.io-shaped transaction tree, so keep page sizes modest for cost predictability. For bulk export workflows use `/api/insiders/bulk/form-4/{year}/{filename}` instead. | 50 |
Response schema
| Field | Type | Nullable | Description |
|---|---|---|---|
| total | object | no | sec-api.io-compatible pagination total: `{ value: integer, relation: 'eq' | 'gte' }`. `relation` is `'eq'` when `value < 10000` (exact count) and `'gte'` otherwise (lower bound). Use `value` for UI page counters; use `relation` to detect when you need to switch to date-range chunking for deeper backfills. |
| transactions | array | no | Array of matching filings — one entry per FILING (NOT one entry per transaction), despite the field name. Each entry carries the full sec-api.io-shaped nested tree (issuer, reportingOwner, nonDerivativeTable, derivativeTable, footnotes). Empty array when no filings match — never null. |
| transactions[].id | string | no | Deterministic document ID (MD5 hash of the accession number). Stable across re-runs. Matches sec-api.io's `id` field. |
| transactions[].accessionNo | string | no | SEC accession number in canonical `XXXXXXXXXX-YY-NNNNNN` format. Matches sec-api.io's `accessionNo` naming. Pass to `GET /insider-module/api/insiders/filings/{accession_number}` to retrieve the same filing in FinRadar's flatter row-oriented shape. |
| transactions[].filedAt | string | yes | ISO-8601 timestamp the filing was accepted by SEC EDGAR (with timezone offset). Distinct from `periodOfReport` (the trade date) — `filedAt` can be up to 2 business days after the trade under the SEC Section 16 filing window. |
| transactions[].schemaVersion | string | yes | Form 4 XML schema version (e.g. `X0306`). Defaults to `X0306` when not present on the filing. |
| transactions[].documentType | string | no | Form type as filed — typically `4` (statement of changes in beneficial ownership), `4/A` (amendment), `3` (initial statement), `5` (annual statement). Filtered server-side to insider-trading forms only — 13F/13D/13G filings never appear here. Matches sec-api.io's `documentType` naming (NOT `formType`). |
| transactions[].periodOfReport | string | yes | ISO `YYYY-MM-DD` Form 4 Item 3 period. Multi-trade filings preserve individual `transactionDate` values inside the nested transaction objects. |
| transactions[].notSubjectToSection16 | boolean | no | `true` when the reporting person is not subject to Section 16. Defaults to `false`. |
| transactions[].issuer | object | no | Issuer block: `{ cik: string (leading zeros stripped), name: string, tradingSymbol: string }`. The company whose securities the insider transacted in. Matches sec-api.io's `issuer` shape. |
| transactions[].reportingOwner | object | yes | SINGLE reporting-owner object (NOT an array) — sec-api.io returns the first reporter for multi-owner filings. Shape: `{ cik, name, address: { street1, street2, city, state, zipCode }, relationship: { isDirector, isOfficer, officerTitle, isTenPercentOwner, isOther } }`. `null` when the filing has no reporter. |
| transactions[].nonDerivativeTable | object | no | Non-derivative table: `{ transactions: [...], holdings: [...] }`. Each transaction has nested `securityTitle`, `transactionDate`, `coding.{formType, code, equitySwapInvolved, footnoteId}`, `amounts.{shares, pricePerShare, acquiredDisposedCode}`, `postTransactionAmounts.{sharesOwnedFollowingTransaction, valueOwnedFollowingTransaction}`, and `ownershipNature.{directOrIndirectOwnership, natureOfOwnership}`. Arrays are empty (not null) when the filing has no non-derivative rows. |
| transactions[].derivativeTable | object | no | Derivative table: `{ transactions: [...], holdings: [...] }`. Same nested shape as the non-derivative transactions plus derivative-specific fields: `conversionOrExercisePrice`, `exerciseDate`, `expirationDate`, `underlyingSecurity.{title, shares}`. Arrays are empty (not null) when the filing has no derivative rows. |
| transactions[].footnotes | array | no | Filing footnotes — array of `{ id: string, text: string }`. Empty array when the filing has no footnotes. |
| transactions[].remarks | string | yes | Free-text remarks from the Form 4 (verbatim). |
| transactions[].ownerSignatureName | string | yes | Name of the person signing the filing. |
| transactions[].ownerSignatureNameDate | string | yes | ISO `YYYY-MM-DD` date the filing was signed. |
Sample response
·
- "total":
- "value": 14
- "relation": "eq"
- "transactions":
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/insider-module/api/insiders/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).