Skip to main content

​
Pull a filed concept series for a model or screen

Use the XBRL API when a model, screen, or research workflow needs a concept-level filed observation rather than a presentation-oriented statement. Keep the number with the reporting context that makes it comparable; a bare value is not enough.

​
Retrieve a concept series

Supply one issuer identifier (ticker, symbol, or cik). tag selects a concept such as Revenues or NetIncomeLoss; taxonomy, unit, form, period, fy, fy_from, and fy_to narrow the observations. Store each returned fact point with its value, periodStart, periodEnd, frame, unit, tag, taxonomy, form, fiscal metadata, accession number, filing URL, and requestedTag, resolvedTag, aliasStrategy, and completeness fields where returned. With no taxonomy or form pinned, the route starts with US-GAAP 10-K/10-Q coverage and can fall back to ifrs-full 20-F/6-K coverage for a foreign private issuer when the US-GAAP lookup is empty. Pin those filters when the research process requires a specific taxonomy or filing family.

​
Facts versus statements

Use the fact route when taxonomy and unit selection are material. Use statements when the consumer needs a conventional financial presentation. Neither route replaces the notes when a policy choice, extension tag, segment, or nonstandard period affects interpretation.

​
SDK and MCP paths

JavaScript uses client.facts({ ticker, tag, period, fy_from, fy_to }); the hosted MCP tool is facts.get with the same issuer, taxonomy/tag, unit, form, and period concepts. facts.get supports historical fiscal-year targeting. Ask the agent to report missing or incompatible fields rather than coerce them to zero.

​
Caveats for model builders

  • An absent tag is not proof that the issuer did not disclose the economic item; the concept may be extension-tagged, differently presented, or outside the selected filters.
  • Do not compare point-in-time balance-sheet facts with duration-based income or cash-flow facts without inspecting their start/end dates, frame, and units. periodBasis applies to normalized statement rows, not fact points.
  • view=agent is compact and drops metadata envelopes. Use the default response for audit storage.
  • The filing URL and accession number are primary evidence. Retrieval metadata describes the API result; it does not elevate a normalized value above the filed document.

​
Next step