Skip to content
/api/v1/xbrl/bulk/facts

Get the latest nightly AS-FILED facts bulk-export manifest: the list of shard files with per-shard row count, byte size, SHA-256 digest, and the `filing_id` range each shard covers, plus the snapshot timestamp, the contract version, the format, and the total shard count.

Get the latest nightly AS-FILED facts bulk-export manifest: the list of shard files with per-shard row count, byte size, SHA-256 digest, and the `filing_id` range each shard covers, plus the snapshot timestamp, the contract version, the format, and the total shard count. The entry point for the facts bulk family — read this, then GET the shard file(s) you need. This is a SEPARATE family from the standardized bulk export (GET /api/v1/xbrl/bulk): its own manifest and its own `latest` pointer.

5 tokensSince v3.106.0

Why use this

Enumerate the nightly as-filed facts inventory before fetching. The corpus is large, so it is split into shard files (one gzip ND-JSON file per block of filings); the manifest lists each shard with its `filing_id_lo`/`filing_id_hi` range, `row_count`, `byte_size`, and `sha256`, plus `generated_at`, `api_version`, `shards_total`, and each shard's `download_path`. Use it to plan which shards to pull and to verify each after fetching.

Common use case

Building a nightly job that mirrors the full as-filed fact store into a warehouse: read the manifest, compare `snapshot` against the last one ingested, and download only the shards whose SHA-256 changed.

Returns the manifest for the most recent completed nightly AS-FILED facts export — the lossless per-fact corpus (xbrl.facts joined to its filing, concept, taxonomy, context and unit). Because the corpus is very large it is exported as SHARD files (one gzip ND-JSON file per block of ~25,000 filings), and the manifest lists each shard with the filing_id range it covers, its row count, byte size and SHA-256 digest. Each fact row carries {filing_id, fact_seq, accession_no, cik, form_type, form_family, fiscal_year, fiscal_period, filed_at, is_current, taxonomy, concept, value, decimals, unit, period, dimensions, is_extension} — the same per-fact shape the GET /api/v1/xbrl/facts route returns, plus lineage fields (filing_id, fact_seq, is_current) for offline dedup and joins. Unlike the /facts route (default amendments=current), the bulk store carries the FULL as-filed history: every fact, current AND superseded, each tagged with is_current; numeric values are strings to preserve full filed precision. This is a SEPARATE family from GET /api/v1/xbrl/bulk (the standardized layer) with its own manifest and latest pointer. Read this manifest, then stream the shard(s) via GET /api/v1/xbrl/bulk/facts/{filename}. 404 NOT_FOUND before the first complete facts export has run.

Response schema

FieldTypeNullableDescription
data.snapshotstringnoThe UTC timestamp identifying the current nightly facts snapshot (e.g. `2026-07-16T07-30-00Z`). Compare against your last-ingested value to detect a fresh export.
data.generated_atstringnoISO-8601 UTC time the snapshot finished generating.
data.api_versionstringnoThe API contract version the export was built against — the per-fact field set matches this version's documentation.
data.formatstringnoThe file format for every shard: `ndjson.gz` — gzip-compressed newline-delimited JSON (one fact object per line).
data.datasetstringnoAlways `facts` for this family — the lossless as-filed fact corpus.
data.file_countintegernoNumber of shard files in the snapshot.
data.total_rowsintegernoSum of `row_count` across all shards — the total as-filed fact count in the corpus.
data.shards_totalintegernoTotal shards the corpus spans (equals `file_count` for a complete snapshot; a snapshot is only published once every shard is present).
data.filesarraynoOne entry per shard: `{dataset, filename, shard_index, filing_id_lo, filing_id_hi, row_count, byte_size, sha256, download_path}`. `filing_id_lo`/`filing_id_hi` are the half-open `filing_id` range the shard covers; `download_path` is the ready-to-call path for GET /api/v1/xbrl/bulk/facts/{filename}.
data.files[].sha256stringnoSHA-256 hex digest of the compressed shard — verify your download against it before ingesting.

Sample response

·
  • "status": "success"
  • "data":
    • "snapshot": "2026-07-16T07-30-00Z"
    • "generated_at": "2026-07-16T07-52-33.881000Z"
    • "api_version": "3.106.0"
    • "format": "ndjson.gz"
    • "dataset": "facts"
    • "file_count": 3
    • "total_rows": 41872553
    • "shards_total": 3
    • "files":
    }
  • "meta":
    • "snapshot": "2026-07-16T07-30-00Z"
    }
}

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 "https://api.finradar.ai/api/v1/xbrl/bulk/facts?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).