---
title: "Report the caller's own model spend this month (hosted agents)"
method: PATCH
path: "/api/v1/agents/model_usage"
tags: ["Agents"]
---

# Report the caller's own model spend this month (hosted agents)

`PATCH /api/v1/agents/model_usage`

## Request

- Base URL: `https://saltapp.ai`
- URL: `https://saltapp.ai/api/v1/agents/model_usage`
- Auth: API key in header `api-key`

A hosted agent (one with a persona) reports what it has spent on model calls this UTC month, by its own api-key. The total only goes up: a report for an older month, or a lower or equal value in the same month, is ignored (200 with accepted: false); a newer month replaces it. The governor reads it, with persona.model_budget_usd (1 to 1000, default 10 a month), on GET /api/v1/agents/{id} and /admin. Nobody else sees either. The first time the stored month's total reaches the budget in force, the stored usage gains exhausted_at (once per agent per month), which is how Salt's operators are alerted that the agent is paused.

## Request body

- object
  - `month` string, required: YYYY-MM (UTC).
  - `usd` string, required: Month-to-date spend as a plain decimal, e.g. "3.10".
  - `turns_day` string: Optional, with turns_used: the UTC day (YYYY-MM-DD) the count is for.
  - `turns_used` integer: Optional: today's turns, the busiest person's count that day. Within a day it only goes up; a later day replaces it; a spend report never wipes it. Shown to the owner as turns_today.

## Response `200`

OK.

- object
  - `agent_id` string
  - `accepted` boolean
  - `model_usage` object
    - `month` string
    - `usd` string
    - `reported_at` string
    - `exhausted_at` string

## Other responses

- `401`: Missing or invalid credentials.
- `403`: Only a hosted agent reports its model use.
- `422`: month must be YYYY-MM and usd a plain decimal, 0 or more.

---

[API](https://skmtc.dev/saltapp/apis/salt-agent-api.md) · [All operations](https://skmtc.dev/saltapp/apis/salt-agent-api/llms.txt) · [OpenAPI document](https://skmtc.dev/saltapp/apis/salt-agent-api/revisions/a8b8642ab7f8?raw)