XBRL companyfacts API: financial observations as JSON

THE SHORT ANSWER

GET /api/v1/facts/{cik} turns SEC companyfacts data into paginated JSON observations. Filter by taxonomy, concept, and unit while retaining the period, filing date, and accession number for every returned value.

Make a real request

Create an API key in your account and set SEC_API_KEY in your shell environment. Keep it server-side. These examples call the authenticated production route; the optional Node base URL override is useful for a separate development environment.

cURL

curl --fail-with-body \
  "https://sec-api.dev/api/v1/facts/320193?taxonomy=us-gaap&concept=Assets&unit=USD&limit=5" \
  -H "Authorization: Bearer $SEC_API_KEY"

Node.js

// Node.js 22+. Set SEC_API_KEY in your environment.
const key = process.env.SEC_API_KEY;
if (!key) throw new Error("Set SEC_API_KEY first");
const base = process.env.SEC_API_BASE_URL || "https://sec-api.dev";
const response = await fetch(
  base + "/api/v1/facts/320193?taxonomy=us-gaap&concept=Assets&unit=USD&limit=5",
  { headers: { Authorization: `Bearer ${key}` } }
);
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
const payload = await response.json();
console.log(payload.data.map(({concept, unit, value, end, accessionNumber}) => ({concept, unit, value, end, accessionNumber})));
console.log(payload.meta);

The examples print the actual response; no sample financial values or filing dates are fabricated.

Choose the concept and unit explicitly

Start with a company CIK and a known taxonomy/concept combination. The example requests us-gaap Assets observations in USD. Taxonomy, concept, and unit filters use exact matches. If you omit a filter, the response can contain observations from multiple concepts or units. That is useful for exploration, but it is not permission to combine unrelated values. Check the returned concept and unit before performing arithmetic or displaying a currency symbol. An absent match remains an empty result; it is never silently replaced with zero.

Keep every observation’s context

The API preserves the source concept, label, description, unit, and value, along with reporting and filing context. end identifies the period end; start is available for duration facts when supplied. filed is the source filing date, and accessionNumber identifies the filing that carried the observation. fiscalYear, fiscalPeriod, and frame may also be present. These fields have different meanings. Do not treat filing date as the measurement period, or choose the final returned row and label it “latest annual” without implementing and documenting a selection rule.

Paginate before deciding what is missing

Limit defaults to 100, with an accepted range of 1–500. Offset defaults to zero. Continue with pagination.nextOffset until it is null when collecting the matching observations. The response groups traversal by taxonomy, concept, and unit; it is not a promise of descending financial-period order. Page-size safeguards can return fewer rows than the requested limit, so use the next offset rather than calculating it from the requested page size. Keep a stable source snapshot for reproducible downstream analysis, and inspect freshness metadata when refreshing your dataset.

Know what companyfacts does not establish

This product exposes observations from SEC companyfacts. It is not an arbitrary XBRL-file converter or a standardized income-statement generator, and it does not claim to extract every custom taxonomy or segment disclosure. A concept can have several observations that require interpretation in context. We do not silently merge those observations into a single preferred financial value. Facts are normally cached for one hour; the response carries the source URL, retrieval time, and stale flag. Verify material interpretations against the original filing and preserve your selection logic separately from the reported data.

Fields to keep

FIELD	HOW TO USE IT
`taxonomy / concept / unit`	The exact source taxonomy, concept identifier, and unit.
`value / start / end`	Reported value and reporting boundaries where present.
`filed / accessionNumber / form`	Filing provenance retained with each observation.
`fiscalYear / fiscalPeriod / frame`	Additional source context when supplied; not interchangeable with dates.
`pagination.nextOffset`	Next page position, or null when the matching set is exhausted.

Authentication, limits, and errors

Every request uses an Authorization: Bearer header. Missing or revoked credentials return 401. Invalid parameters return 400, account limits return 429, and service or source failures return 5xx. Inspect the status before processing data, respect retry guidance, and avoid unbounded retry loops. API responses include a request ID for troubleshooting. Account allowances are listed on pricing; endpoint limits and response definitions are in the API reference.

Source and implementation boundary

The underlying data comes from SEC companyfacts and XBRL API documentation. The public SEC data source can be accessed directly; sec-api.dev adds its documented authentication, caching, response structure, and integration workflow. Source retrieval time describes our cache, not a guarantee of source publication latency. We are independent of the SEC and sec-api.io.