/api/insiders/bulk/form-{form_type}/{year}/{filename}Download a monthly bulk data file as gzip-compressed JSONL (one JSON object per line).
Download a monthly bulk data file as gzip-compressed JSONL (one JSON object per line). Each line is a complete filing record with issuer, owners, transactions, holdings, footnotes, and signatures. Files are pre-generated when available, or streamed on-the-fly if not yet cached.
25 tokensSince v3.14.0
Why use this
Retrieve a signed S3 download URL for one month's worth of insider filings as gzip-compressed JSONL — one filing per line, fully nested with issuer + reporters + non-derivative/derivative transactions + holdings + footnotes + signatures (matches the per-filing `/insiders/filings/{accession_number}` shape). The bulk-export workflow for quantitative research: backtest insider-signal strategies on 20+ years of Form 4 history, build a local database mirror, or train models on the full event-time stream. Pair with `/bulk/form-{form_type}/index.json` to enumerate available months first, then fetch each file via this endpoint. The 24-hour signed-URL TTL gives you ample window for download retries; for fresh URLs after expiry, just re-call (the underlying file is cached for 7 days, so re-call is fast).
Common use case
Bulk downloading all Form 4 filings from 2024 for quantitative research, backtesting insider trading strategies, or building a local database mirror.
Returns a signed S3 URL for a specific bulk-export JSONL.gz file (one transaction per line, gzipped). 24h TTL on the signed URL. Locate filenames via GET /api/insiders/bulk/form-{form_type}/index.json. Bulk files cover one calendar month and are regenerated nightly to incorporate late amendments.
Parameters
| Name | In | Required | Default | Allowed | Description | Example |
|---|---|---|---|---|---|---|
| form_type | path | required | — | — | SEC insider-trading form type — `3` (initial statement), `4` (changes — highest volume), or `5` (annual statement). Same set as the index endpoint's `form_type` parameter. | 4 |
| year | path | required | — | — | 4-digit calendar year of the file (e.g. `2025`). Coverage starts 2003 (SEC's electronic Form 4 mandate). Returns 404 for years outside coverage. | 2025 |
| filename | path | required | — | — | Bulk file name in `form-{type}-{YYYY}-{MM}.jsonl.gz` format. Get exact filenames from `/bulk/form-{form_type}/index.json` — DO NOT hand-construct (filename schema may evolve). Returns 404 if the filename doesn't match any indexed file. | form-4-2025-09.jsonl.gz |
Response schema
| Field | Type | Nullable | Description |
|---|---|---|---|
| download_url | string | no | Signed S3 download URL valid for 24 hours from response time. Direct download — no auth required for the URL itself, signature handles authorization. Stream the response with `gzip` decompression; do NOT load the full uncompressed payload into memory for large months (Form 4 monthly files uncompress to 50-80 MB). |
| filename | string | no | Filename echoed back, useful for asserting your client's path-construction matched what was retrieved (especially when constructing from an enumeration loop). |
| row_count | integer | no | Number of JSONL lines (= filings) in the file. Use for download-completeness verification: after gunzip, your client should see exactly `row_count` lines (`wc -l`) — any mismatch indicates a partial download, retry. |
| size_bytes | integer | no | Compressed file size in bytes. Use for `Content-Length` validation against the S3 download — mismatches indicate a corrupted or partial download. |
| sha256 | string | no | SHA-256 hex digest of the gzipped file contents. Compute the SHA-256 of the downloaded blob locally and compare to assert integrity before processing — critical for any pipeline that depends on byte-exact reproducibility. |
| expires_at | string | no | ISO-8601 UTC timestamp when the signed URL expires (always `now + 24h`). After expiry the URL returns 403 — re-call this endpoint to mint a fresh signed URL (cheap; cache hit on the underlying file for up to 7 days). |
Sample response
·
- "download_url": "https://finradar-bulk.s3.amazonaws.com/form-4/2026/form-4-2026-04.jsonl.gz?X-Amz-Signature=..."
- "filename": "form-4-2026-04.jsonl.gz"
- "row_count": 28432
- "size_bytes": 4128000
- "sha256": "a1b2c3d4..."
- "expires_at": "2026-05-02T20:55:12.000Z"
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}/{year}/{filename}?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).