---
title: "Read an agent's month envelope and usage"
method: GET
path: "/v1/commerce/mcp/agent/budgets/{agentId}"
---

# Read an agent's month envelope and usage

`GET /v1/commerce/mcp/agent/budgets/{agentId}`

## Request

- Base URL: `https://api.decionis.com`
- URL: `https://api.decionis.com/v1/commerce/mcp/agent/budgets/{agentId}`
- Auth: HTTP bearer

The operator-set envelope for the agent, what its closed runs used this UTC month, what its active runs still reserve, and what remains. Without an envelope the view carries usage only.

## Path parameters

- `agentId` string, required

## Response `200`

Validated bounded response; private, no-store

- BudgetView
  - `version` 'commerce-agent-run-v1', required
  - `org_id` string, uuid, required
  - `agent_id` string, required
  - `period` object, required
    - `kind` 'utc_month', required
    - `starts_at` string, date-time, required
    - `ends_at` string, date-time, required
  - `envelope` object, nullable, required
    - `actions` integer, required
    - `exposure` object, required
      - `amount` number, required
      - `currency` string, required
    - `revision` integer, required
    - `updated_at` string, date-time, required
  - `usage` object, required
    - `runs` integer, required
    - `active_runs` integer, required
    - `actions` object, required
      - `used` integer, required
      - `reserved` integer, required
      - `remaining` integer, nullable, required
    - `exposure` object, required
      - `used` number, required
      - `reserved` number, required
      - `remaining` number, nullable, required
      - `currency` string, nullable, required
    - `agent_cost` object, required
      - `proposals` integer, required
      - `input_tokens` integer, required
      - `output_tokens` integer, required
      - `amount` number, required
      - `currency` string, nullable, required
  - `trailing` object[], required
    - `period` object, required
      - `kind` 'utc_month', required
      - `starts_at` string, date-time, required
      - `ends_at` string, date-time, required
    - `runs` integer, required
    - `actions_used` integer, required
    - `exposure_used` number, required
    - `agent_cost_amount` number, required
  - `execution_available` unknown, required

## Other responses

- `400`: Malformed, unconfirmed, mismatched or dossier-less PROCEED input
- `401`: Missing or invalid credential
- `403`: Write scope, role or dossier access denied
- `404`: Feature disabled, run or dossier unavailable to this organization
- `409`: Rebound idempotency key or dossier mismatch; never automatically retry a write
- `413`: Request exceeds route byte limit
- `429`: Durable identity/IP limit exceeded; Retry-After supplied
- `503`: Authority, storage or evidence unavailable; completion may be unconfirmed

---

[API](https://skmtc.dev/decionis/apis/decionis-commerce-gate-api.md) · [All operations](https://skmtc.dev/decionis/apis/decionis-commerce-gate-api/llms.txt) · [OpenAPI document](https://skmtc.dev/decionis/apis/decionis-commerce-gate-api/revisions/9fecb7109bf8?raw)