# Prometheus 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 Prometheus
(https://www.prometheus.services). The point of using Prometheus over a web
search is that every number comes with its source filing. Your output should
carry that through: **numbers with accession numbers and periods, never bare
figures.**

Read `/agents.md` for the rules. The contract is `/openapi.json`. Base URL is
`https://www.prometheus.services`. 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 prometheus-terminal`, `PROMETHEUS_API_KEY=pk_live_...`, then
`prom --json search nvidia`, `prom --json financials NVDA -q`,
`prom --json fact-source NVDA std:revenue 2025-01-26 -q`, `prom transcript NVDA`
(the date is resolved for you), `prom event NVDA <accession>` (the item code
is resolved for you). Exit codes: 0 ok · 2 usage · 3 auth · 5 not found ·
6 rate limited · 7 server. Docs: https://doc.prometheus.services/cli

## The loop

1. **Resolve the entity.** `GET /api/v1/search?q=<name>` returns companies
   (with ticker and CIK), macro series and countries. Prefer the CIK over the
   ticker as `id` when a company has changed symbols or has several share
   classes.

2. **Pull the right surface, once.**
   - Fundamentals → `GET /api/v1/companies/{id}/financials?period_type=quarterly`
     (or `annual`). One call returns the full standardized income statement,
     balance sheet and cash flow for up to 200 periods. Do not page line by line.
   - "What did they originally report?" → add `reporting_basis=as_reported`.
   - 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=<code>` — 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.
   - Correlation and charting vocabularies (which companyIds, indicator codes,
     metrics, symbols are valid) 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=<SERIES>`; the payload is
     point-in-time, so the value for a date is what was known on that date.
   - Second-order effects → `GET /api/v1/intelligence/graph?focus=<node>` then
     `POST /api/v1/intelligence/simulate` with `{nodeId, magnitudePct}`.

3. **Trace before you quote.** For any figure you will state, call
   `GET /api/v1/companies/{id}/fact-source?statement=<s>&key=<line>&end_date=<YYYY-MM-DD>&period_type=<p>`.
   It returns the XBRL concept, the filing accession, and the calculation tree
   the line was derived from. 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 Prometheus 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://www.prometheus.services/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` → Data Center segment by quarter.
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?...` 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. |