Query API

The read endpoints answer the questions the dashboard answers: what am I spending, where is it going, and what's about to run out. Authenticate with a bearer API key; base URL https://api.argus.town.

GET/overview

The whole workspace in one call — the dashboard's front page as JSON. Per-provider metrics and advisories, 56 days of daily spend broken down by provider, and workspace totals.

curl https://api.argus.town/overview -H "Authorization: Bearer argus_mcp_..."

GET/connections

Your connected providers: id, provider, label, status (active / invalid / expired), and when each last synced. Provider credentials are never returned by any endpoint.

GET/connections/:id/events

The itemized ledger — one row per call your app made, with the cost Argus settled on and where that number came from:

{
  "id": "01JF8…",
  "endpoint": "/v1/chat/completions",
  "model": "anthropic/claude-sonnet-4.5",
  "status": 200,
  "latency_ms": 412,
  "cost_usd": 0.0159,
  "cost_provenance": "provider_reported",   // or app_reported | derived | unpriced
  "units": { "input_tokens": 900, "output_tokens": 120 },
  "metadata": { "run_id": "run_42" },
  "occurred_at": 1753060000
}

limitnumberoptional

Rows per page, up to 500. Default 100.

beforeunix secondsoptional

Cursor for older pages: pass the occurred_at of the oldest row you have.

all0 | 1optional

By default you get costed or failed calls — the interesting ones. all=1 includes every request.

GET/providers/:id

One provider in depth, keyed by connection id: current metrics, 90 days of daily usage, cost broken down by model, the plan Argus detected, live rate-limit windows, and recent sync runs.

GET/alerts

Your alert rules and their recent fires, newest first.

GET/billing

Argus metering itself: your plan, and this month's usage against it (events ingested, tracked spend).

GET/providers/catalog/:id

Public — no auth. Reference knowledge of a provider's commercial shape: pricing model, plans (with included allowances and overage mode), unit prices, rate limits, exhaustion behavior, and what Argus can meter. Useful before you connect a provider, or to explain a bill. /providers/catalog (no id) lists every provider's model and summary. Numbers carry a confidence marker.

POST/connections

Connect a provider: { "provider", "secret", "credential_type"?, "label"? }. The credential is validated against the provider before it's stored (encrypted), and the initial sync is queued. Keys are project-scoped, so this creates the connection in the key's project only.

POST/connections/:id/sync

Queue an immediate balance/usage/plan refresh.

DELETE/connections/:id

Remove a connection and its entire ledger — events, usage history, everything cascades. This is the one endpoint worth pausing on before calling from automation.

A note on paths

The canonical paths are the short ones above. You may also see /api/overview-style paths — they're the same endpoints and both forms work.

← Authentication Sending telemetry →