Recipe: Look up company financials

The task

You need a public company’s core numbers — revenue, net income, cash, debt — sourced from what they actually filed with the SEC, not a scrape or a third-party estimate, and you want to know exactly which filing each number came from.

Tool used: get_company_financials — one call, most-recent-10-K snapshot with the filing attached to every figure. The rest of this page covers when to reach for something else instead (a time series, raw filings, a live quote, a peer comparison).

Copy-paste prompt

Give me <company>'s most recent revenue, net income, cash, and total debt using Pipeworx's SEC
data — not an estimate. Name the filing (form + date) each figure came from, and flag it if any
figure is from a fiscal year I didn't ask for.

What a good answer looks like

get_company_financials({ company: "AAPL" })

returns (live call, 2026-08-06 — trimmed to the fields that matter):

{
  "cik": "320193",
  "entity_name": "Apple Inc.",
  "period_end": "2025-09-27",
  "fiscal_year": 2025,
  "revenue": {
    "tag": "RevenueFromContractWithCustomerExcludingAssessedTax",
    "val": 416161000000,
    "accn": "0000320193-25-000079",
    "fy": 2025, "fp": "FY", "form": "10-K", "filed": "2025-10-31"
  },
  "net_income": {
    "tag": "NetIncomeLoss",
    "val": 112010000000,
    "accn": "0000320193-25-000079",
    "form": "10-K", "filed": "2025-10-31"
  },
  "cash_and_equivalents": {
    "tag": "CashAndCashEquivalentsAtCarryingValue",
    "val": 35934000000,
    "form": "10-K", "filed": "2025-10-31"
  },
  "eps_diluted": { "tag": "EarningsPerShareDiluted", "val": 7.46, "form": "10-K" }
}

A trustworthy answer has, on every metric block:

• tag — the exact XBRL concept the company actually filed under (e.g. RevenueFromContractWithCustomerExcludingAssessedTax, not a generic “Revenue” label the tool made up). Different companies use different tags for the same real-world line item; this field is how you check the tool used the right one for this filer.
• form + filed — which filing this came from and when it was filed, so you can tell a fresh annual figure from a stale one.
• fiscal_year / period_end at the top level — the period this whole snapshot covers. Check it against what you asked for before repeating a number: the default is the most recent 10-K, which may be a full fiscal year behind “today.”
• accn — the SEC accession number of the specific filing, citable and re-fetchable.

A plausible-sounding failure looks like a well-formed, fully-structured JSON blob with real numbers and real dates — for the wrong concept. This is a real, live example, not a hypothetical:

// sec-xbrl's RAW concept lookup — you supply the tag yourself, no auto-resolution
get_company_concept({ cik: "320193", taxonomy: "us-gaap", tag: "Revenues" })
// → tag: "Revenues", units.USD: [
//     { value: 215639000000, period_end: "2016-09-24", form: "10-K", filed: "2018-11-05" },
//     { value: 78351000000,  period_end: "2016-12-31", form: "10-K", filed: "2018-11-05" },
//     ... nothing newer than fiscal 2016-2018 ...
//   ]

Apple moved off the generic Revenues tag to RevenueFromContractWithCustomerExcludingAssessedTax after adopting ASC 606 — the years-old Revenues values are still legitimately in SEC’s dataset (nothing is broken), but reading them as “Apple’s revenue” without checking the tag and dates tells a stale, wrong story with a completely plausible-looking response. get_company_financials and edgar_company_concept (below) both auto-resolve to the tag a filer is currently using; the raw sec-xbrl.get_company_concept does not — it returns exactly whatever tag you name, silently, even if that tag went dormant years ago.

Step-by-step tool calls

Decision tree

Worked examples

One-call snapshot (shown above):

get_company_financials({ company: "AAPL" })
// company accepts a CIK or a ticker — ticker auto-resolves

What did Apple file recently:

edgar_company_filings({ ticker_or_cik: "AAPL", limit: 5 })
// → 10-Q filed 2026-07-31, 8-K filed 2026-07-30, Form 4s, ... with document_url per filing

Revenue over time, current tag auto-resolved:

edgar_company_concept({ cik: "0000320193", concept: "Revenues", period: "annual" })
// → concept: "RevenueFromContractWithCustomerExcludingAssessedTax" (resolved, not "Revenues")
//   latest: { fiscal_year: 2025, period_end: "2025-09-27", value: 416161000000, form: "10-K" }

Note this is the same friendly input (“Revenues”) that produced stale data above — the difference is edgar_company_concept resolves it per-filer; the raw sec-xbrl tool does not.

Compare AAPL, MSFT, GOOGL:

compare_entities({ type: "company", values: ["AAPL", "MSFT", "GOOGL"] })
// → one call, parallel: Revenues/NetIncomeLoss/Cash/LongTermDebtNoncurrent for all three,
//   each with concept_used naming the resolved tag, plus a deltas block for side-by-side compare

Current stock price (requires a BYO Alpha Vantage key — the shared demo key is rate-limited constantly; get a free key in 30 seconds at https://www.alphavantage.co/support/#api-key):

av_quote({ symbol: "AAPL", _apiKey: process.env.ALPHAVANTAGE_KEY })
// → { price, volume, change, change_percent, latest_trading_day }

Browse available tags before a raw concept lookup (this is sec-xbrl.get_company_facts — called here by its collision-resolved gateway name, since another pack exports a same-named tool; connect scoped to just the sec-xbrl pack and the bare name works too):

sec_xbrl_get_company_facts({ cik: "320193" })
// → { taxonomies: [{ taxonomy: "us-gaap", concept_count: 503, sample_tags: [...] }, ...] }

Use this to see what a company actually reports before calling the raw get_company_concept — it won’t tell you which tag is current, only which tags exist.

Pattern: full company brief

const [snapshot, filings, quote] = await Promise.all([
  get_company_financials({ company: "AAPL" }),
  edgar_company_filings({ ticker_or_cik: "AAPL", limit: 5 }),
  av_quote({ symbol: "AAPL", _apiKey: KEY }),  // omit if no BYO key
])

Citation pattern

Apple Inc. (AAPL, CIK 0000320193) reported FY2025 revenue of $416.16B (10-K, filed 2025-10-31). Full XBRL history per SEC XBRL facts. Current quote $X (alphavantage, live).

Caveats

• CIK formats vary. SEC accepts both 320193 and 0000320193 (zero-padded). The packs handle both — don’t manually pad.
• Fiscal year alignment. Apple’s fiscal year ends in September; calendar-year-Q1 numbers don’t align with Apple’s Q1. Every response carries fy/fp (fiscal year/period) — use those, not calendar-quarter assumptions.
• A generic tag name can point at abandoned data. “Revenues” works for many filers, but companies that adopted ASC 606 largely moved to RevenueFromContractWithCustomerExcludingAssessedTax — the live example above. Prefer get_company_financials or edgar_company_concept, which auto-resolve the filer’s current tag, over the raw sec-xbrl get_company_concept/get_company_facts unless you specifically need to browse or pin an exact tag.
• get_company_facts is ambiguous on the gateway — two different packs export a tool by that exact name, so it’s exposed as sec_get_company_facts and sec_xbrl_get_company_facts respectively. get_company_financials and edgar_company_concept don’t have this problem; prefer them and you won’t need to remember the prefix.
• Small / foreign issuers. Non-US companies that file 20-F or 6-K work in edgar. Companies that don’t file with the SEC at all (private, foreign-only-listed) don’t appear — try open-corporates instead.
• Alpha Vantage free tier is 25 calls/day, shared-demo-key traffic gets rate-limited constantly. For sustained use, bring your own key or stick to sec-xbrl/edgar (no rate limits).