Skip to content
/api/v1/sec/filings/backfill

Explicitly backfill ALL historical filings for a ticker from SEC EDGAR.

Explicitly backfill ALL historical filings for a ticker from SEC EDGAR. Fetches the complete filing history from data.sec.gov/submissions/ and stores it locally. Subsequent GET queries will return the full history instantly.

freeSince v1.0.0

Why use this

Explicit, free (cost: 0) trigger to pre-load the FULL submissions history for a ticker from SEC EDGAR's `data.sec.gov/submissions/CIK{cik}.json` endpoint into FinRadar's local index. Use this to warm the cache before running an analysis batch — once a ticker has been backfilled, every subsequent call to `GET /api/v1/sec/filings?ticker=X` hits the local DB instantly (no SEC round-trip). Cost is zero because the work is one-shot per-ticker — repeated backfills detect the existing rows via the `(accession_number, cik)` UNIQUE constraint and only insert deltas. Idempotent: safe to call multiple times — `inserted` will be 0 on no-op repeat calls.

Common use case

Call POST /filings/backfill?ticker=AAPL to load all ~2000 Apple filings in one shot, then query them instantly with GET /filings?ticker=AAPL.

Pre-loads the complete SEC submissions history for a ticker from data.sec.gov/submissions/CIK{cik}.json into FinRadar's local sec_filing_entries index. Idempotent and free (cost: 0) — safe to call before a batch analysis run to warm the cache. Subsequent calls to GET /api/v1/sec/filings hit the local index instantly (no SEC round-trip). Returns 502 BAD_GATEWAY when SEC EDGAR is unreachable; returns 404 when the ticker cannot be resolved to a CIK. The auto-backfill machinery in GET /api/v1/sec/filings calls this internally on first-touch for any unknown ticker — most clients never need to call it directly. Useful for: (a) pre-warming an offline analysis batch, (b) recovering after the local index has been pruned, (c) running a forced refresh when you suspect the local index is stale.

Parameters

NameInRequiredDefaultAllowedDescriptionExample
tickerqueryrequired——Stock ticker to backfill (e.g. XAIR, AAPL, TSLA)AAPL

Response schema

FieldTypeNullableDescription
statusstringnoAlways `"success"` on 2xx. ApiResponse envelope marker — wraps via `ApiResponse.success()`.
request_idstringyesPer-request UUID generated server-side. Surface this in support tickets — operations can grep it directly out of nginx + main_api logs.
timestampstringnoISO-8601 UTC timestamp the response was generated server-side (suffix `Z`).
dataobjectnoBackfill result envelope — see `data.*` for fields. Wall-clock duration scales with how many filings the issuer has — typically 2-15s for an issuer with 500-3000 historical filings; longer for very-tenured issuers (e.g. GE, IBM) which can have 10K+ filings.
data.tickerstringnoEchoed input ticker after Phase-53 normalization (e.g. `BRK.A` → `BRK-A`). Useful for confirming the resolution before relying on it downstream.
data.cikstringno10-char zero-padded CIK resolved from the input ticker. Use this as the join key for follow-up queries against XBRL, 13F, or insider-filing tables.
data.companystringnoResolved entity name (e.g. `Apple Inc.`). Useful as a display label for the backfilled batch.
data.insertedintegernoCount of NEW filings inserted into the local index by this call (rows that didn't exist before). 0 on a no-op repeat call. Compare against `total_from_edgar` to gauge completeness.
data.already_existedintegernoCount of EDGAR filings that were already in the local index (skipped via the `(accession_number, cik)` UNIQUE constraint). On a fresh-ticker backfill: 0. On a repeat call: equals `total_from_edgar`.
data.total_from_edgarintegernoTotal count of filings returned by SEC EDGAR's submissions API for this CIK. Equals `inserted + already_existed + errors`.
data.errorsintegernoCount of EDGAR rows that failed to ingest (parse errors, transient DB issues). Should typically be 0 — non-zero values indicate a parse-edge-case worth filing a support ticket for. Errors are logged server-side with the accession number.

Sample response

·
  • "status": "success"
  • "request_id": "0f14ed05-3a2e-4b76-9c11-1a7c8b3f6de2"
  • "timestamp": "2026-05-02T16:30:14.122Z"
  • "data":
    • "ticker": "AAPL"
    • "cik": "0000320193"
    • "company": "Apple Inc."
    • "inserted": 1843
    • "already_existed": 0
    • "total_from_edgar": 1843
    • "errors": 0
    }
}

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/sec/filings/backfill" \
  -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).