/api/insiders/bulk/form-{form_type}/index.jsonGet index of available monthly bulk download files for a form type.
Get index of available monthly bulk download files for a form type. Returns list of available months with file size, record count, generation date, and download URL. Status is 'available' (pre-generated) or 'pending' (will be generated on first download).
25 tokensSince v3.14.0
Why use this
Discover the bulk-data inventory before fetching individual files — returns the full list of monthly Form 3/4/5 bulk export files with file sizes, row counts, generation timestamps, and SHA-256 digests for integrity verification. The right entry point for any bulk-export workflow: enumerate this first to find the months you need, then drill into `/bulk/form-{form_type}/{year}/{filename}` to retrieve signed download URLs. Files cover one calendar month each, regenerated nightly to incorporate late amendments. Files older than 12 months are kept in cold storage with ~1 minute extra latency on first surface — once warmed, subsequent index calls return them instantly.
Common use case
Building a bulk data download page that shows available months, file sizes, and record counts — like SEC EDGAR's full-text search bulk download index.
Lists monthly bulk-export files available for a form type (3, 4, 5). Each entry carries a YYYY/MM filename, file size, row count, and SHA-256 digest. Use this to enumerate available files before fetching them via GET /api/insiders/bulk/form-{form_type}/{year}/{filename}. The 25-token cost reflects the heavy back-end aggregation of the index. Files older than 12 months are kept in cold storage and may take an extra minute to surface.
Parameters
| Name | In | Required | Default | Allowed | Description | Example |
|---|---|---|---|---|---|---|
| form_type | path | required | — | — | SEC insider-trading form type to enumerate. Accepts `3` (initial statement of beneficial ownership — filed when an insider first joins), `4` (statement of changes — every transaction; the highest-volume), or `5` (annual statement — captures missed Form 4 filings). Form 4 is the most-requested for trading analytics; Forms 3 and 5 are typically only relevant for compliance / governance research. | 4 |
Response schema
| Field | Type | Nullable | Description |
|---|---|---|---|
| form_type | string | no | Form type echoed back (`3`, `4`, or `5`). Useful for asserting your client's request resolved correctly. |
| files | array | no | Array of monthly bulk-file metadata rows, sorted by `(year, month) DESC` (most-recent month first). Coverage starts in 2003 (the SEC's electronic Form 4 mandate). Empty array on form types with no bulk coverage (won't happen in practice — all 3 form types are covered). |
| files[].year | integer | no | Calendar year of the file's coverage period (e.g. `2026`). Combined with `month` forms the file's coverage window. |
| files[].month | integer | no | Calendar month 1-12 of the file's coverage period. Files cover the calendar month exactly (no fiscal-period offset). |
| files[].filename | string | no | Bulk file name in `form-{type}-{YYYY}-{MM}.jsonl.gz` format (e.g. `form-4-2026-04.jsonl.gz`). Pass to `/bulk/form-{form_type}/{year}/{filename}` to retrieve the signed download URL. |
| files[].row_count | integer | no | Number of JSONL lines (= filings) in the gzipped file. Form 4 monthly files: typically 25K-35K; Form 3: 1K-3K; Form 5: 0.5K-2K. Use for client-side cost-budgeting before download. |
| files[].size_bytes | integer | no | Compressed file size in bytes (post-gzip). Form 4 monthly files: typically 4-8 MB compressed (~50-80 MB uncompressed). Form 3 and Form 5 files: < 1 MB. Plan downstream consumer pipelines accordingly. |
| files[].sha256 | string | no | SHA-256 hex digest of the gzipped file contents. Use for download-integrity verification — the bulk-fetch endpoint returns the same SHA, so client code can assert the downloaded blob matches before processing. |
| files[].generated_at | string | no | ISO-8601 UTC timestamp when this file was last regenerated. Files are regenerated nightly to incorporate late amendments — values within the last 24 hours indicate a fresh generation; older values indicate the cold-storage path is being served. |
Sample response
·
- "form_type": "4"
- "files":
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 "https://api.finradar.ai/api/insiders/bulk/form-{form_type}/index.json?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).