stocks_get_peers

Comparable companies for one company, with fundamentals side by side.

Use this right after resolving a company, when the question is "who does this trade against?" or "how does it compare to its peers?" — it returns the comparison set and the metrics in one bounded call. Use stocks_screen instead when you already know the criteria and want to rank or page the whole cross-section, and stocks_get_financial_metrics when you only need one company's own multi-period detail.

Peers are active-listed companies sharing the subject's classification in the platform's own SIC-derived taxonomy (SEC SIC codes mapped by us; no licensed vendor taxonomy is involved). data.basis says which cut was used: sic-major-group — same 2-digit SEC SIC major group inside the same sector, the tighter and preferred set when the subject has a SIC code — or sector, the fallback when the subject has no SIC code or its major group contains no other listed company. data.sector and data.sic_major_group echo the classification used.

Ordering is nearest fundamental scale: ascending absolute log-ratio of trailing-annual revenue against the subject, so a peer twice the size ranks the same distance away as one half the size. Companies with no comparable revenue value sort last, alphabetically.

data.subject is the subject's own row (it is never listed among its peers) and data.peers holds the comparison rows. Every row carries ticker, cik, company_name, exchange, sector, sic_code, and metrics: exact-decimal values with unit, currency, fiscal frame, as_of, and source. data.peer_universe_size is how many companies the basis matched — larger than the returned list means you are seeing the closest slice. meta.as_of is when the metrics snapshot last rebuilt.

A subject we have not classified (no SIC, or one outside our mapping) returns basis: null, peers: [], and a reason saying so — a normal success, not an error.

Results are bounded: default 10 peers, maximum 20, and there is no paging (pagination is null) — this is a nearest-N answer, so use stocks_screen to enumerate a full cross-section. Metrics are bounded at 10 per row, counted on what is served: revenue is always one of them, so name at most 10 metrics including revenue, or at most 9 that are not — 10 non-revenue names is one too many and is rejected as bad_parameter.

Errors carry a machine code: unknown_entity for a symbol or CIK we hold no company for, bad_parameter for an unknown metric name or an out-of-range bound, and out_of_license when a public request names a price-derived metric (market_cap, pe_ttm, ps_ttm, pb, ev_ebitda, fcf_yield) — the same gate stocks_screen applies.

Example: stocks_get_peers(ticker_or_cik="AAPL", limit=10, metrics=["revenue", "net_margin", "roe"]).