Costs

Govrix Scout tracks token usage and USD cost for every proxied request. Costs are stored in PostgreSQL via a materialized view backed by the TimescaleDB events hypertable. Budget enforcement (per-agent and global daily caps) reads from the same budget_daily table that these endpoints query.

`GET /api/v1/costs/summary`

Returns aggregate token usage and USD cost across all agents for the available date range.

Auth required: Yes


curl -H "Authorization: Bearer $GOVRIX_API_KEY" \
  http://localhost:4001/api/v1/costs/summary

Response 200 OK:


{
  "total_cost_usd": 14.2837,
  "total_prompt_tokens": 1842500,
  "total_completion_tokens": 412300,
  "total_tokens": 2254800,
  "date_from": "2026-03-01T00:00:00Z",
  "date_to": "2026-03-05T23:59:59Z",
  "agent_count": 4,
  "request_count": 9871
}

Fields:

Field	Type	Description
`total_cost_usd`	float	Total USD cost across all agents and models
`total_prompt_tokens`	integer	Cumulative input tokens
`total_completion_tokens`	integer	Cumulative output tokens
`total_tokens`	integer	Sum of prompt + completion tokens
`date_from`	string	Earliest event timestamp in the dataset
`date_to`	string	Latest event timestamp in the dataset
`agent_count`	integer	Number of distinct agents with recorded events
`request_count`	integer	Total number of proxied requests

`GET /api/v1/costs/breakdown`

Returns cost and token usage broken down per agent, sorted by total_cost_usd descending. Use this to identify top spenders and enforce accountability.

Auth required: Yes


curl -H "Authorization: Bearer $GOVRIX_API_KEY" \
  http://localhost:4001/api/v1/costs/breakdown

Response 200 OK:


[
  {
    "agent_id": "agt_01hx9z2k3mq4n5p6r7s8t9u0v",
    "agent_name": "billing-agent",
    "total_cost_usd": 9.1204,
    "total_prompt_tokens": 1102000,
    "total_completion_tokens": 248500,
    "total_tokens": 1350500,
    "request_count": 5821,
    "avg_cost_per_request_usd": 0.001566,
    "models_used": ["gpt-4o", "gpt-4o-mini"]
  },
  {
    "agent_id": "agt_02jy0a3l4nr5o6q7s8t9u1w2x",
    "agent_name": "support-agent",
    "total_cost_usd": 4.3901,
    "total_prompt_tokens": 620500,
    "total_completion_tokens": 142300,
    "total_tokens": 762800,
    "request_count": 3812,
    "avg_cost_per_request_usd": 0.001152,
    "models_used": ["claude-3-5-sonnet-20241022"]
  },
  {
    "agent_id": "agt_03kz2c5o6pt7r8s9u1v2w4y5z",
    "agent_name": "data-pipeline-agent",
    "total_cost_usd": 0.7732,
    "total_prompt_tokens": 120000,
    "total_completion_tokens": 21500,
    "total_tokens": 141500,
    "request_count": 238,
    "avg_cost_per_request_usd": 0.003249,
    "models_used": ["gpt-4o"]
  }
]

Fields per agent:

Field	Type	Description
`agent_id`	string	Agent ID
`agent_name`	string	Agent name as registered
`total_cost_usd`	float	Total USD cost for this agent
`total_prompt_tokens`	integer	Cumulative input tokens
`total_completion_tokens`	integer	Cumulative output tokens
`total_tokens`	integer	Sum of prompt + completion tokens
`request_count`	integer	Number of requests from this agent
`avg_cost_per_request_usd`	float	Mean cost per request
`models_used`	string[]	Distinct model IDs used by this agent