Recipe: Look up company financials

Three Pipeworx packs cover public-company finance, each with a different specialty. Picking wrong wastes calls and confuses output. This recipe routes the question to the right pack.

Tools used: edgar_company_filings, edgar_company_facts, sec-xbrl.get_company_facts, alphavantage.av_quote, alphavantage.av_overview, compare_entities.

Calls: 1–4.

Decision tree

The shapes of failure

edgar_company_filings({ ticker_or_cik: undefined }) previously crashed with “Cannot read properties of undefined (reading ‘trim’).” It now returns a clear “Required argument missing” error. Either way: always pass a non-empty ticker or CIK string.

alphavantage free tier is 25 calls/day per key. The shared demo key is hammered constantly and returns rate-limit errors. Bring your own key — get one free in 30 seconds at https://www.alphavantage.co/support/#api-key.

Worked examples

”What did Apple file in the last quarter?"

edgar.edgar_company_filings({
  ticker_or_cik: "AAPL",
  limit: 20
})
// → recent filings: 10-Q, 8-K, etc. with accession numbers and document URLs

"Apple’s 10-K text"

const filings = await edgar.edgar_company_filings({
  ticker_or_cik: "AAPL",
  form_type: "10-K",
  limit: 1
})
// document_url points to the actual 10-K HTML — fetch it directly with WebFetch or wikipedia.fetch_url

"Apple revenue over the last 5 years”

// Lookup CIK if needed
const { cik } = await edgar.edgar_ticker_to_cik({ ticker: "AAPL" })

// Get all XBRL facts for the company
const facts = await sec-xbrl.get_company_facts({ cik })
// Pull Revenues from facts.facts['us-gaap']['Revenues'].units.USD — array of {start, end, val, fy, fp, form}

For specific concepts:

sec-xbrl.get_company_concept({ cik: "320193", concept: "Revenues" })

“Compare AAPL, MSFT, GOOGL”

compare_entities({
  type: "company",
  values: ["AAPL", "MSFT", "GOOGL"]
})
// → side-by-side revenue, income, market cap, in one parallel gateway call

This is the one-call form. The meta-tool fans out to edgar/sec-xbrl/alphavantage in parallel and reconciles results.

”Current AAPL price”

// Requires alphavantage BYO key passed via _apiKey arg
alphavantage.av_quote({ symbol: "AAPL", _apiKey: process.env.ALPHAVANTAGE_KEY })
// → {price, volume, change, change_percent, latest_trading_day}

Pattern: full company brief

// Resolve identity once
const { cik, ticker } = await resolve_entity({ type: "company", value: "Apple" })

// Parallelize the fetches
const [filings, facts, quote, overview] = await Promise.all([
  edgar.edgar_company_filings({ ticker_or_cik: ticker, limit: 5 }),
  sec-xbrl.get_company_facts({ cik }),
  alphavantage.av_quote({ symbol: ticker, _apiKey: KEY }),
  alphavantage.av_overview({ symbol: ticker, _apiKey: KEY }),
])

Four packs, one parallel block, full picture in <1 second of wall time.

Citation pattern

Apple Inc. (AAPL, CIK 320193) reported Q1 revenue of $X billion (10-Q). Five-year revenue trend per SEC XBRL. 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. XBRL data has fp (fiscal period) and fy (fiscal year) — use those, not calendar dates.
• XBRL concept names are inconsistent across companies. “Revenues” works for most, but some use “RevenueFromContractWithCustomerExcludingAssessedTax.” If a concept lookup returns empty, browse get_company_facts to see what concepts the company actually reports.
• 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.
• Ratelimits on alphavantage. Free tier 25 calls/day. For sustained use, upgrade or use sec-xbrl + edgar (no rate limits).