Skip to content
/api/v1/xbrl/bulk/facts/{filename}

Download one shard file from the latest nightly AS-FILED facts snapshot.

Download one shard file from the latest nightly AS-FILED facts snapshot. The response body is the raw gzip ND-JSON shard streamed from disk (never buffered into memory), with `Content-Disposition: attachment` and the `X-Bulk-Snapshot` header naming the snapshot. Supports HTTP Range requests and conditional (If-Modified-Since) requests, so a large download is resumable. Shard filenames come from the manifest's `files[].filename` (or `download_path`).

25 tokensSince v3.106.0

Why use this

Fetch a single facts shard (e.g. `facts_p00001.ndjson.gz`) as a streamed gzip download. Decompress and read one fact object per line. Verify the bytes against the manifest's `sha256` before ingesting.

Common use case

Pulling the full as-filed fact corpus into a warehouse: GET the facts manifest, then GET each `facts_p*.ndjson.gz` shard, gunzip, and COPY the ND-JSON rows into your own tables; keep only the shards whose SHA-256 changed since your last mirror.

Streams one shard from the current nightly as-filed facts snapshot straight off disk — the file is never loaded into memory, and the transfer supports Range + conditional requests so a multi-hundred-MB shard resumes cleanly. The success body is the gzip file itself (not the JSON envelope); the X-Bulk-Snapshot response header tells you which snapshot you got. Always fetch GET /api/v1/xbrl/bulk/facts first to learn the valid shard filenames and their SHA-256 digests, then verify the downloaded bytes against the digest before ingesting. Errors use the standard JSON error envelope: 400 INVALID_PARAM (malformed filename), 404 NOT_FOUND (no complete export yet, or the shard is not in the current snapshot).

Parameters

NameInRequiredDefaultAllowedDescriptionExample
filenamepathrequired——The facts shard to download, exactly as listed in the manifest's `files[].filename`. Only the current snapshot's `facts_p<N>.ndjson.gz` shard files are served. An unknown or malformed name returns 400 `INVALID_PARAM`; a name not in the current snapshot returns 404 `NOT_FOUND`.facts_p00001.ndjson.gz

Response schema

FieldTypeNullableDescription
(binary)stringnoThe raw gzip ND-JSON shard bytes (Content-Type `application/gzip`). This endpoint does NOT return the JSON envelope on success — it streams the file. Errors (400/404) DO use the standard JSON error envelope.

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/facts_p00001.ndjson.gz?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).