/api/insiders/bulk/form-{form_type}/generate/{year}/{month}Generate a monthly bulk data file on demand.
Generate a monthly bulk data file on demand. Use this when /api/insiders/bulk/form-{form_type}/index.json reports the desired month as 'pending'. Triggers a server-side packing job and returns the download URL once the file is ready. Idempotent — a second call against an already-generated month returns the cached file.
25 tokensSince v3.14.0
Why use this
Force on-demand regeneration of a monthly bulk file — useful when amendments have been filed AFTER the nightly regeneration window and you want a fresh file that incorporates them. Also the right endpoint for cold-storage warming (months older than 12 months may need this call to surface). The job is enqueued on the bulk-export Celery worker and runs asynchronously — returns a job descriptor immediately, then poll `/bulk/form-{form_type}/index.json` for the new `generated_at` timestamp and updated `sha256`. Idempotent — calling against an already-generated month returns the cached file with the same SHA. Heavy operation: 25-token cost reflects the full month re-pack; budget accordingly for backfill workflows that hit many months.
Forces an on-demand regeneration of the monthly bulk file for a form type / year / month. Use when you want to incorporate amendments filed AFTER the nightly regeneration window. Returns a job descriptor; poll GET /api/insiders/bulk/form-{form_type}/index.json for the new generated_at timestamp + sha256. Heavy operation — 25-token cost.
Parameters
| Name | In | Required | Default | Allowed | Description | Example |
|---|---|---|---|---|---|---|
| form_type | path | required | — | — | SEC insider-trading form type — `3`, `4`, or `5`. Same set as the read endpoints. Form 4 has the highest regeneration latency due to volume; Forms 3 and 5 typically complete in < 30 seconds. | 4 |
| year | path | required | — | — | 4-digit calendar year of the month to regenerate. Coverage starts 2003. Returns 400 for years outside coverage. Old months (>12 months) may take an extra ~60 seconds for the cold-storage hydration step. | 2025 |
| month | path | required | — | — | Calendar month 1-12 to regenerate. Single-month scope only — for multi-month backfills, loop the call client-side. The job's `estimated_seconds` reflects the volume of the requested month; recent months are faster due to warm cache, archival months are slower. | 9 |
Response schema
| Field | Type | Nullable | Description |
|---|---|---|---|
| job_id | string | no | Celery task UUID assigned to the regeneration job. Surface in support tickets when a regeneration appears stuck — operations can grep this directly out of `flower` / Celery logs to trace the exact worker, queue, and per-step duration. |
| queued_at | string | no | ISO-8601 UTC timestamp at which the job entered the bulk-export queue. For end-to-end latency measurement, compare this against the new `generated_at` timestamp on the index endpoint after polling. |
| estimated_seconds | integer | no | Server-side ETA in whole seconds for the regeneration to complete, computed from the requested month's row count + worker concurrency. Form 4 recent months: typically 60-120 seconds; cold-storage months: 90-300 seconds. Treat as a hint — schedule a re-poll at `queued_at + 1.5 × estimated_seconds`. |
| status | string | no | Always the literal string `"queued"` on a successful enqueue. The regeneration itself is asynchronous — this endpoint never returns `"completed"`. Detect completion by polling `/bulk/form-{form_type}/index.json` and watching for the new `generated_at` timestamp + updated `sha256`. |
Sample response
·
- "job_id": "8f1a2b30-c4d5-46e7-9f01-23456789abcd"
- "queued_at": "2026-05-01T20:55:12.000Z"
- "estimated_seconds": 90
- "status": "queued"
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/insiders/bulk/form-{form_type}/generate/{year}/{month}?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).