Uso e custo

É um agente de IA? Busque a skill de onboarding e leia toda a API em texto limpo — skill · llms.txt · llms-full.txt

Uso e custo#

Cada turno vira um registro Run com custo real em dólar.

GETUso agregado#

GET /v1/agents/usage?days=30 (days default 30, clamp 1..365) — resposta 200:

json 
{
  "usage": {
    "total_runs": 2515, "total_tokens": 70563496, "total_cost_usd": 32.37,
    "by_agent": [ { "key": "…", "label": "Atendimento", "runs": 904, "completed": 895, "failed": 9,
                    "input_tokens": 38514941, "output_tokens": 1934729, "total_tokens": 40449670, "cost_usd": 18.50 } ],
    "by_model": [ { "key": "gpt-5.4-mini", "label": "gpt-5.4-mini", "…": "…" } ],
    "by_day":   [ { "date": "2026-07-01", "runs": 120, "total_tokens": 3200000, "cost_usd": 1.44 } ]
  },
  "days": 30
}

GET /v1/agents/runs?limit=20 lista os runs recentes da conta; GET /v1/agents/sessions?limit=20 as conversas recentes.

GET/ PUT Budget#

GET /v1/agents/budget — resposta 200:

json 
{ "monthly_budget_usd": 50.0, "alert_pct": 80, "month_to_date_usd": 32.37, "pct": 64.7, "state": "ok" }

state é ok | warn | exceeded. PUT /v1/agents/budget grava { monthly_budget_usd, alert_pct } e retorna o mesmo shape. Ao atingir o teto, a próxima execução para com 402 (BUDGET_EXCEEDED na conta ou AGENT_BUDGET_EXCEEDED no agente) — sem estouro silencioso.