---
title: "Read account usage"
method: GET
path: "/v1/users/{userID}/usage"
---

# Read account usage

`GET /v1/users/{userID}/usage`

## Request

- Base URL: `https://api.plori.ai`
- URL: `https://api.plori.ai/v1/users/{userID}/usage`
- Auth: HTTP bearer

Only the authenticated account owner can use this route. Members use their own credentials and cannot manage another account. Returns usage totals and groups by person, API key, agent, tool and workflow.

## Path parameters

- `userID` string, uuid, required

## Response `200`

Account usage, including attributed people.

- AccountUsage: Account usage. Monetary integers are micro-US-dollars. People and API keys group attributed run spend.
  - `totals` object, required
    - `credits` integer, required
    - `tokens` integer, required
    - `runs` integer, required
  - `by_role` object, required
    - `executor` object, required
      - `credits` integer, required
      - `tokens` integer, required
      - `calls` integer, required
    - `advisor` object, required
      - `credits` integer, required
      - `tokens` integer, required
      - `calls` integer, required
    - `reviewer` object, required
      - `credits` integer, required
      - `tokens` integer, required
      - `calls` integer, required
  - `by_kind` object[], required
    - `kind` string, required
    - `credits` integer, required
    - `tokens` integer, required
    - `events` integer, required
  - `tools` object[], required
    - `tool` string, required
    - `calls` integer, required
    - `free_calls` integer, required
    - `credits` integer, required
  - `agents` object[], required
    - `agent_id` string, uuid, required
    - `name` string, required
    - `backend` string, required
    - `credits` integer, required
    - `tokens` integer, required
    - `events` integer, required
    - `breakdown` object[]
      - `kind` string, required
      - `name` string
      - `credits` integer, required
      - `tokens` integer, required
      - `events` integer, required
  - `people` object[], required
    - `user_id` string, uuid, required
    - `email` string, required
    - `credits` integer, required
    - `runs` integer, required
  - `api_keys` object[], required
    - `key_id` string, uuid, required
    - `name` string, required
    - `kind` string, required
    - `revoked` boolean, required
    - `credits` integer, required
    - `runs` integer, required
  - `workflows` object[], required
    - `workflow_id` string, uuid, required
    - `name` string, required
    - `billed_runs` integer, required
    - `exec_credits` integer, required
    - `model_credits` integer, required
    - `credits` integer, required
    - `tokens` integer, required
  - `workflow_executions` object[], required
    - `id` string, uuid, required
    - `workflow_id` string, uuid, required
    - `workflow_name` string, required
    - `status` string, required
    - `fault` string
    - `trigger_source` string, required
    - `duration_ms` integer, required
    - `credits` integer, required
    - `created_at` string, date-time, required
    - `ended_at` string, date-time
  - `recent_runs` object[], required
    - `id` string
    - `agent_id` string, uuid
    - `workspace_id` string, uuid: The Workspace the run belongs to; omitted for runs outside a Workspace.
    - `thread_id` string, uuid
    - `status` string
    - `actor` object: Workspace run list only: the credential that started the run. Absent when none is recorded.
      - `kind` 'key' | 'web'
      - `key_id` string
      - `key_name` string
      - `revoked` boolean
    - `origin` 'user' | 'schedule' | 'background' | 'agent' | 'agent_result'
    - `parent_run_id` string
    - `started_at` string, date-time
    - `ended_at` string, date-time
    - `last_heartbeat_at` string, date-time
    - `cause` 'user_stop' | 'workspace_stop' | 'input_expired' | 'run_superseded' | 'credits_exhausted' | 'task_budget_exhausted' | 'workspace_save_refused' | 'interrupted' | 'stalled' | 'time_limit' | 'vm_capacity_unavailable' | 'backend_error' | 'spawn_failed' | 'workspace_copy_held' | 'account_disk_full' | 'agent_deleted': Machine-readable terminal cause. After time_limit or stalled the saved work continues with a new message; vm_capacity_unavailable means no VM slot became free before the placement wait ended, and the same message can be sent again. task_budget_exhausted appears only on runs that ended before task group token figures stopped limiting model calls.
    - `retryable` boolean
    - `credits` integer, nullable: Amount charged for the run, in micro-USD (µ$), where 1,000,000 µ$ = $1.
    - `tokens` integer, nullable
    - `stop_reason` string
    - `agent_name` string, required
    - `workspace_name` string
    - `task_text` string, required

## Other responses

- `400`: Malformed request.
- `401`: Missing or invalid credential.
- `403`: The resource belongs to another account.
- `500`: Internal error with request_id.

---

[API](https://skmtc.dev/plori/apis/plori-rest-api.md) · [All operations](https://skmtc.dev/plori/apis/plori-rest-api/llms.txt) · [OpenAPI document](https://skmtc.dev/plori/apis/plori-rest-api/revisions/2234a20f0150?raw)