Tools reference

All tools are read-only: none changes data or acts on your behalf. From Python, pass the arguments by name to call:

call("get_financials", ticker="AAPL", metric_id="revenue", period_type="FY")

Search metric catalogue

search_metrics(query, limit=25)

Find metric ids by name, alias or definition, ranked by how many companies report each.

Metric ids such as 'revenue', 'cfo' or 'kpi.same_store_sales_growth_pct' are the keys used by get_financials, compare_companies and the obs table in run_sql. There are about 82,000, so ids are found here rather than guessed. The most widely reported match is usually the standard one.

Parameters:	query – words to match, e.g. "free cash flow" or "same store sales". limit – how many metrics to return, 1 to 100.

Get reported financials

get_financials(ticker, metric_id, period_type='Q', fy_from=None, fy_to=None, limit=40)

Reported values of one metric for one company, newest first, with the SEC filing for each period.

Each row is a reported actual: its fiscal and calendar period, period end date, value, unit and currency, what kind of figure it is (income statement, balance sheet, cash flow, per-share, company KPI, or calculated by Stock Atlas), and the 10-K or 10-Q that covers that period with its EDGAR link. Stock Atlas holds no analyst estimates.

Parameters:	ticker – exchange ticker, e.g. "AAPL". metric_id – an id from search_metrics, e.g. "revenue" or "kpi.total_customers_count". period_type – "Q" quarterly, "FY" annual, or "QE" for balance-sheet values at quarter end. fy_from – earliest fiscal year to include, optional. fy_to – latest fiscal year to include, optional. limit – maximum rows, 1 to 500.

Compare companies on one metric

compare_companies(tickers, metric_id, period_type='FY', fy_from=None, fy_to=None)

One metric side by side for several companies, period by period.

Rows carry both the fiscal period and the calendar quarter that contains the period's end date; calendar_year and calendar_quarter line up companies whose fiscal years end in different months, and are empty for some rows. Values are reported actuals with their unit.

Parameters:	tickers – two to 25 exchange tickers, e.g. ["ORLY", "AAP"]. metric_id – an id from search_metrics, e.g. "kpi.same_store_sales_growth_pct". period_type – "FY" annual, "Q" quarterly, or "QE" balance sheet at quarter end. fy_from – earliest fiscal year, optional. fy_to – latest fiscal year, optional.

Get company guidance

get_guidance(ticker, metric=None, target_period=None, include_revisions=False, limit=50)

Company guidance from 8-K earnings releases, with the reported actual where one exists.

Each row is a forecast the company itself issued: the metric, the target period (e.g. "FY2026" or "2026-Q3"), the earnings release it came in, the guided low, high and value (the midpoint where a range was given), and, once the period has been reported, the actual result and whether it came in above, within or below guidance. By default only the latest guide for each metric and target is returned. sec_8k_filings_url opens the company's 20 most recent 8-K filings on EDGAR as of 100 days after the reported quarter ended, which normally includes the earnings release.

Parameters:	ticker – exchange ticker, e.g. "HUBS". metric – optional words to match the guided metric, e.g. "revenue" or "eps". target_period – optional "FY2026", "2026-Q3" or "2026". include_revisions – true returns every vintage, showing how guidance changed. limit – maximum rows, 1 to 200.

Show where a figure came from

get_provenance(ticker, metric_id, period_end=None)

Where a reported figure came from: source, filing reference, confidence tier and any recorded conflicts.

For checking or citing a specific number. tier describes how the value was confirmed: 'tier_a…' values are witness- or filing-confirmed, 'G_…' are anchored to EDGAR, 'C…' are arithmetic derivations, and a null tier means no provenance tier has been assigned.

Parameters:	ticker – exchange ticker. metric_id – an id from search_metrics. period_end – optional ISO date to narrow to one period, e.g. "2024-09-28".

Run read-only DuckDB SQL

run_sql(sql)

Run one read-only query in DuckDB SQL against the Stock Atlas warehouse.

The database is DuckDB; the dialect is documented at https://duckdb.org/docs/stable/sql/introduction and the Stock Atlas tables and columns at https://stockatlas.com/docs/data/#tables (describe_table lists them too). Suited to screens, rankings and comparisons across many companies. Accepts a single SELECT, WITH, DESCRIBE, SUMMARIZE, SHOW or EXPLAIN statement; each query is limited to 20 seconds and 500 returned rows. Tables: obs, metric, metric_canonical, prices, bridge, filings, guidance, guidance_outcome, conflicts, kpi_coverage, build_meta.

Parameters:	sql – one DuckDB SQL statement.

Describe a table

describe_table(table)

The columns and types of one Stock Atlas table, for writing run_sql queries.

Parameters:	table – one of obs, metric, metric_canonical, prices, bridge, filings, guidance, guidance_outcome, conflicts, kpi_coverage, build_meta.