# USA Outlays

> A public ledger of U.S. government spending: contract and grant awards (who got
> paid, how much, for what) plus the approvals and funding decisions that
> authorized them. 60M+ award records across all 50 states, organized under one
> policy taxonomy. Built for spending trends nationwide — contract detail is
> extra granularity for verification.

## Data layers (never collapsed)

- **Awards** — outlays (paid), reimbursements, and obligations (signed
  contracts/encumbrances not yet paid; excluded from outlay totals).
- **Approvals** — the authorizing layer: legislature budget votes, county
  commission and city council spending decisions, utility/water/school boards,
  special districts.

## Taxonomy

Nested specific → general tree: award → program → topic → domain → function
(L1–L3 curated, L4 programs discovered from data), plus orthogonal facets:
sector, level, procurement type, funding mechanism, competition,
procurement method, lifecycle, instrument, integrity. Classification is on
spending purpose, not agency identity.

## Reading the data honestly

- Amounts are **stated**, not verified cash movement. Missing values display as
  "not disclosed", never zero.
- Contract ceilings and IDIQ ceilings are flagged and **excluded from spend
  totals** — never sum them.
- One record per entry: exactly one primary topic per award, one facet row per
  (award_id, facet).

## Machine access

- REST API: `https://usa-outlays.ai/api/v1` — key via `x-api-key` header (or
  `?api_key=`). Subscriptions at /pricing — or pay per call: **$3.40 for one
  API call, no account needed**. Buy at /pricing; a single-use token is
  delivered instantly (one request, 24h expiry). Built for agents that just
  need an answer.
- Ask endpoint: `POST /api/v1/ask` with `{"question": "..."}` — an agent
  resolves the question to the taxonomy and returns a summary answer, the
  supporting taxonomy, and a raw data packet. One question = one call.
  Example: "what is the policing budget of utah".
- Data surfaces: curated awards/approvals (/api/v1/awards, /api/v1/approvals),
  raw as-ingested records (/api/v1/raw/awards), taxonomy tree (/api/v1/topics).
- OpenAPI spec: https://usa-outlays.ai/openapi.json
- MCP server: https://github.com/qchasan/usa-outlays/tree/main/mcp
  (`search_awards`, `search_approvals`, `get_vendor`, `topic_tree`,
  `fulltext_search`, `coverage`)
- Capability manifest: https://usa-outlays.ai/.well-known/usa-outlays.json

## Docs

- Full agent brief: https://usa-outlays.ai/llms-full.txt
- Agent landing page: https://usa-outlays.ai/agents
- Human API docs: https://usa-outlays.ai/api-docs
- Signup: https://usa-outlays.ai/pricing