# Astreus skill — answer financial questions with citable data You are answering a question about a public company, an executive, a macro series or a market theme using Astreus (https://astreus.ai) — a financial data terminal that turns companies', exchanges' and central banks' own disclosure (filings, results announcements, investor decks, earnings calls, 8-Ks, policy text) into structured, traceable data across the US, the Gulf, Japan, Taiwan, Korea and Europe. The point of using Astreus over a web search is that every number comes with its source filing, page or passage. Your output should carry that through: **numbers with accession numbers and periods, never bare figures.** If the question is about what Astreus covers (a market, a data type, how far back), call `GET /api/v1/landing/coverage` (public; MCP `get_coverage`; CLI `astreus coverage`) and answer from it — never from memory. Read `/agents.md` for the rules. The contract is `/openapi.json`. Base URL is `https://astreus.ai`. Send `X-API-KEY: pk_live_...` (or `Authorization: Bearer pk_live_...`) on everything except the endpoints marked public; the user creates keys on the Developers page in the terminal. If you have a shell, the CLI does this loop with less ceremony: `npm i -g astreus-cli`, `ASTREUS_API_KEY=pk_live_...`, then `astreus --json search nvidia`, `astreus --json financials NVDA -q`, `astreus --json fact-source NVDA std:revenue 2025-01-26 -q`, `astreus transcript NVDA` (the date is resolved for you), `astreus event NVDA ` (the item code is resolved for you). Exit codes: 0 ok · 1 unexpected · 2 usage · 3 auth · 4 payment · 5 not found · 6 rate limited · 7 server. Docs: https://doc.astreus.ai/cli If your environment speaks MCP, connect instead of scripting HTTP: hosted — `claude mcp add --transport http astreus https://astreus.ai/api/mcp --header "Authorization: Bearer pk_live_..."`; local stdio — `claude mcp add astreus --env ASTREUS_API_KEY=pk_live_... -- astreus mcp`. The tools mirror this loop (`search` → `get_financials` → `get_fact_source`, plus filings, events, news, transcripts, guidance, macro, themes) and their descriptions carry these same rules. Docs: https://doc.astreus.ai/mcp-server ## The loop 1. **Resolve the entity.** `GET /api/v1/search?q=` returns companies (with ticker and CIK or platform key), macro series and countries. Prefer the CIK over the ticker as `id` when a company has changed symbols or has several share classes; for a non-SEC issuer (Tadawul, DFM, ADX, TSE, TWSE, KRX, …) always use the platform key the payload returns as `cik` (`XSAU000001`) — a bare ticker resolves to the SEC registrant. 2. **Pull the right surface, once.** - Fundamentals → `GET /api/v1/companies/{id}/financials?period_type=quarterly` (or `annual`, or `semiannual` for half-year filers). One call returns the full standardized income statement, balance sheet, cash flow, ratios and the segments & KPIs statement for up to 200 periods. Do not page line by line. Statement rows are keyed `std:` (`std:revenue`); columns are period labels whose end dates are in `period_meta`. - "What did they originally report?" → `GET /api/v1/companies/{id}/financials/as-filed?statement=income_statement&vintage=original` (each period from the filing the company made for it). `/financials` is latest-restated; `reporting_basis=as_reported` there means cumulative year-to-date quarters, not the original vintage. - Revenue by segment, product, brand or region → `/segment-revenue` and `/regional-revenue` (latest block, with `source.accession` or the deck slide); the full history is the `segments_kpis` statement in `/financials`. - Inside the notes → `/filing-notes` (sections as text at `/{sectionId}`), `/filing-notes/tables` (gated note tables: inventories, debt, leases, receivables, taxes …), `/filing-notes/series?family=` (one family across every filing). Investor decks → `/presentations`. - What management promised → `/earnings/promises`; whether they delivered → `/earnings/scorecard`. - What happened recently → `/events` (8-Ks by family) or the cross-company `/api/v1/events/wire?q=...`. Full text of one 8-K item → `/events/{accession}?item=` — take both values from the events index; the response is plain text, not JSON. - Transcript text → `/transcripts/{transcriptId}?date=YYYY-MM-DD` — both id AND date come from the transcript index; the response is plain text. - Charting vocabularies (which companyIds, indicator codes, metrics, symbols are valid for `POST /api/v1/charting/series`) come from `GET /api/v1/correlation/catalog` — fetch it before building a request body. - Who owns / who sold → `/ownership` and `/ownership/transactions`. - Macro → `GET /api/v1/countries/{iso}/series?key=`; the payload is the current vintage (the latest published value for each period), not what was known on a past date. 3. **Trace before you quote.** For any figure you will state, call `GET /api/v1/companies/{id}/fact-source?statement=&key=&end_date=&period_type=

` with the row key exactly as `/financials` returned it (`std:revenue`, an XBRL tag, `seg::…`, `kpi::…`; `statement=segments_kpis` for the last two). It returns the XBRL concept (or the printed cell and page for PDF-sourced issuers), the filing accession or document reference, and the arithmetic behind derived values (`provenance: derived_q4` etc.). Put the accession and period end next to the number in your answer. 4. **Handle gaps honestly.** A null line means the serving gate withheld it or the company never reported it. Write "not available in Astreus for that period", never 0, never an estimate presented as data. 5. **Answer, then stop.** State the figures, the periods, the filings, and any restatement caveat. Do not recommend a trade. If the user asks for one, point them to the site's terms (https://astreus.ai/terms#not-advice). ## Worked example > "What was NVIDIA's data-center revenue growth last quarter, and did it beat > what management guided?" 1. `GET /api/v1/search?q=nvidia` → ticker NVDA, CIK 1045810. 2. `GET /api/v1/companies/NVDA/segment-revenue` → latest fiscal-year revenue by product/segment (Compute, Networking, Gaming …) with its `source.accession`; the quarterly series for a member is in `GET /api/v1/companies/NVDA/financials?period_type=quarterly` under `segments_kpis`, and any of its cells is citable with `fact-source?statement=segments_kpis&key=`. 3. `GET /api/v1/companies/NVDA/earnings/scorecard` → the guidance commitment for that quarter and its outcome. 4. `GET /api/v1/companies/NVDA/fact-source?statement=income_statement&key=std:revenue&end_date=&period_type=quarterly` for the total-revenue line to cite the 10-Q accession. 5. Answer: growth figure with both periods, the guided range, the outcome label from the scorecard, the accession numbers. ## Errors | Status | Meaning | Do | |---|---|---| | 401 | Key missing, revoked, or malformed | Ask the user for a valid API key. Don't loop. | | 402 | `upgrade_required` | Tell the user it needs Pro. Don't bypass. | | 404 | Unknown id, symbol, period or accession | Re-resolve via `/search`. | | 429 | `rate_limited` or `quota_exceeded` | Sleep `Retry-After` seconds; if quota_exceeded, tell the user their monthly quota is spent. |