---
title: "List every agent with an envelope or a run this month"
method: GET
path: "/v1/commerce/mcp/agent/budgets"
---

# List every agent with an envelope or a run this month

`GET /v1/commerce/mcp/agent/budgets`

## Request

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

One budget view per agent that has an operator envelope or a run in the current UTC month, alphabetically, at most 200 with truncation explicit. Each carries the three previous months' usage so an operator can size the envelope.

## Response `200`

Validated bounded response; private, no-store

- BudgetList
  - `version` 'commerce-agent-run-v1', required
  - `org_id` string, uuid, required
  - `period` object, required
    - `kind` 'utc_month', required
    - `starts_at` string, date-time, required
    - `ends_at` string, date-time, required
  - `budgets` object[], required
    - `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
  - `coverage` object, required
    - `limit` unknown, required
    - `truncated` boolean, 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)