---
title: "Read a run's state, budgets, horizon and recent proposals"
method: GET
path: "/v1/commerce/mcp/agent/runs/{id}"
---

# Read a run's state, budgets, horizon and recent proposals

`GET /v1/commerce/mcp/agent/runs/{id}`

## Request

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

A run past its horizon reads as expired. Only the credential's organization can read its runs.

## Path parameters

- `id` string, uuid, required

## Response `200`

Validated bounded response; private, no-store

- Run
  - `version` 'commerce-agent-run-v1', required
  - `run_id` string, uuid, required
  - `org_id` string, uuid, required
  - `state` 'active' | 'stopped' | 'exhausted' | 'expired', required
  - `objective` 'hold_margin_floor' | 'hold_inventory_floor' | 'review_orders' | 'review_refunds' | 'review_promotions' | 'release_payments', required
  - `allowed_action_types` string[], required
  - `scope` object, required
    - `platforms` string[], required
    - `skus` string[]
    - `order_ids` string[]
  - `agent` object, required
    - `id` string, required
  - `budget` object, required
    - `actions` object, required
      - `granted` integer, required
      - `used` integer, required
      - `remaining` integer, required
    - `exposure` object, required
      - `granted` number, required
      - `used` number, required
      - `remaining` number, required
      - `currency` string, required
  - `horizon` object, required
    - `started_at` string, date-time, required
    - `ends_at` string, date-time, required
  - `proposals` object, required
    - `count` integer, required
    - `by_outcome` object, required
      - `PROCEED` integer, required
      - `HOLD` integer, required
      - `ESCALATE` integer, required
      - `BLOCK` integer, required
    - `refused` integer, required
    - `recent` object[], required
      - `proposal_id` string, uuid, required
      - `action_type` 'PRICE_CHANGE' | 'INVENTORY_MUTATION' | 'ORDER_ACCEPTANCE' | 'FULFILLMENT_ACTION' | 'PROMOTION_CHANGE' | 'REFUND_REQUEST' | 'RETURN_AUTHORIZATION' | 'PAYMENT_RELEASE' | 'VENDOR_BANK_CHANGE' | 'EARLY_PAYMENT_DISCOUNT' | 'CREDIT_HOLD_RELEASE', required
      - `platform` string, required
      - `outcome` 'PROCEED' | 'HOLD' | 'ESCALATE' | 'BLOCK', required
      - `dossier_id` string, uuid, nullable, required
      - `amount` number, nullable, required
      - `recorded_at` string, date-time, required
  - `stop` object, nullable, required
    - `reason` string, required
    - `stopped_at` string, date-time, required
  - `agent_cost` object, required
    - `proposals` integer, required
    - `input_tokens` integer, required
    - `output_tokens` integer, required
    - `amount` number, required
    - `currency` string, nullable, required
  - `durability` 'process_memory' | 'backend_ledger', required
  - `execution_available` unknown, required
  - `no_downstream_action_executed` unknown, required
  - `created_at` string, date-time, required
  - `updated_at` string, date-time, 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)