> ## Documentation Index
> Fetch the complete documentation index at: https://ara-90a60a07.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# Get usage summary
> Returns a window's model usage per model and per agent (a Session's lead agent, or the helper agents it spawned), and cloud machine usage per size, with tokens and the RCU charged. These are the totals the Usage settings page shows. Every member may read it. Returns 400 `invalid_user_id` when `user_id` is not a UUID.
Scope: `analytics:read`
## OpenAPI
````yaml /openapi.json get /v3/organizations/{orgId}/usage/summary
openapi: 3.1.0
info:
title: Reason API
version: 3.0.0
description: >-
The Reason HTTP API. Drive cloud software-engineering agents: open sessions
against your repositories, stream their work, and manage the secrets,
skills, and automations they run with.
Authenticate with a Reason API key sent as a bearer token. New keys use
`reason_`; legacy `ara_` keys remain accepted. Every resource is scoped to
an organization; resolve your `org_id` once with `GET /v3/self`.
servers:
- url: https://api.reasonmachines.com
security:
- reasonApiKey: []
tags:
- name: Account
description: Verify a key and resolve the organization it belongs to.
- name: Reasons
description: >-
Start here. A Reason is the long-running agent a person keeps: their main
Reason and named ones, each with its own instructions, default model and
repositories, conversation, Loops and Sessions. Give a Reason work by
messaging it (sendReasonMessage) and read its replies with
listReasonMessages.
- name: Loops
description: >-
Standing work a Reason does, woken by a schedule or an event: a webhook, a
GitHub event or a Slack message. Each wake opens or continues a Session of
the Reason; webhook events that share a correlation key continue one
Session.
- name: Memory
description: >-
What Reasons remember across Sessions. Each Session starts by reading
MEMORY.md (a short index) and the list of topic notes, and reads a note
when its topic comes up. `personal` memory belongs to one person (the API
key's owner) and only their Sessions read it; `team` memory belongs to the
Workspace and every member's Sessions read it. memory:read lists, reads
and searches; memory:write writes and deletes, in team memory only for a
Workspace owner or admin.
- name: Sessions
description: >-
A Session is one run of work inside a Reason: every Reason message and
Loop wake runs in one, and createSession starts one directly for a single
unattended task with a pass/fail outcome. Its transcript, events, result
and pull request are read here.
- name: Skills
description: >-
Reusable instruction bundles Reason selects semantically from their
descriptions for matching agent tasks.
- name: Secrets
description: >-
Encrypted credentials injected into the agent's sandbox. Write-only:
values can be set but never read back.
- name: Attachments
description: >-
Files uploaded to the organization and shared with sessions, downloaded
via short-lived signed URLs.
- name: Repositories
description: Connected repositories, their indexing state, and generated wikis.
- name: Git Connections
description: Linked source-control accounts and the repositories they expose.
- name: Machines
description: >-
Named Workspace queues served by headless workers. Sessions target a
Machine by name and wait for a free worker; more workers serve more
Sessions concurrently.
- name: Devices
description: >-
Owned Mac and headless Device identity, bounded enrollment and root
grants.
- name: Cloud Access
description: >-
Keyless cloud sign-in for sessions: Reason's OIDC issuer facts and the
AWS, Google Cloud and Azure connections a workspace trusts, including
which run triggers each one signs in.
- name: MCP Servers
description: >-
Org-level Model Context Protocol servers exposed to the agent. Secret
values are write-only.
- name: Change Request Reviews
description: >-
Automated senior-engineer reviews posted on pull requests and merge
requests.
- name: Consumption
description: 'Billing-aligned usage: daily consumption and billing cycles.'
- name: Metrics
description: Aggregate analytics over sessions, change requests, and usage.
- name: Audit Logs
description: An append-only record of changes made within the organization.
- name: Organizations
description: The top-level tenant. Create, read, update, and delete organizations.
- name: Members
description: People in an organization and their pending invites.
- name: Roles
description: Role assignments that govern what each member can do.
- name: Settings
description: 'Organization configuration: namespaced settings and the run tag policy.'
- name: Provider credentials
description: >-
Configure Bring-Your-Own-Key (BYOK) API keys and subscription credentials
for model providers. Secret values are write-only.
- name: Feedback
description: Report problems with the API or these docs to the Reason team.
- name: Projects
description: >-
Deprecated: a project is a Reason with the same id. Use the Reasons
operations; these remain for existing clients.
- name: Automations
description: >-
The older form of Loops. Prefer the Loops under a Reason (listReasonLoops,
createReasonLoop), which take every wake: schedule, webhook, GitHub,
Slack. Use these for what Loops do not carry yet: a run's MCP and app
tools, and automations not filed under a Reason.
paths:
/v3/organizations/{orgId}/usage/summary:
parameters:
- $ref: '#/components/parameters/orgId'
get:
tags:
- Consumption
summary: Get usage summary
description: >-
Returns a window's model usage per model and per agent (a Session's lead
agent, or the helper agents it spawned), and cloud machine usage per
size, with tokens and the RCU charged. These are the totals the Usage
settings page shows. Every member may read it. Returns 400
`invalid_user_id` when `user_id` is not a UUID.
Scope: `analytics:read`
operationId: getUsageSummary
parameters:
- in: query
name: start_date
schema:
type: string
format: date-time
description: >-
Beginning of the window. Omit it to start 30 days before `end_date`.
A window longer than 92 days is cut to its latest 92 days.
- in: query
name: end_date
schema:
type: string
format: date-time
description: >-
End of the window, excluded. Omit it, or pass a later time, to end
the window now.
- in: query
name: user_id
schema:
type: string
format: uuid
description: Counts only this member's usage. Omit it for the whole workspace.
responses:
'200':
description: Usage summary.
content:
application/json:
schema:
$ref: '#/components/schemas/UsageSummary'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'429':
$ref: '#/components/responses/RateLimited'
security:
- reasonApiKey:
- analytics:read
components:
parameters:
orgId:
name: orgId
in: path
required: true
description: Organization id or slug. Resolve it with `GET /v3/self`.
schema:
type: string
schemas:
UsageSummary:
type: object
properties:
models:
type: array
items:
$ref: '#/components/schemas/UsageModelSummary'
description: Usage per model, billing and provider, most tokens first.
agents:
type: array
items:
$ref: '#/components/schemas/UsageAgentSummary'
description: >-
The same usage split by agent role: per role, model, billing and
provider. Leads first, then helpers, each most tokens first.
machines:
type: array
items:
$ref: '#/components/schemas/UsageMachineSummary'
description: Cloud machine usage per rate and provider, longest running first.
totals:
type: object
properties:
total_tokens:
type: number
description: Input plus output tokens across every model.
runtime_seconds:
type: number
description: Cloud machine running time, in seconds.
rcu:
type: number
description: RCU charged for models and machines.
required:
- total_tokens
- runtime_seconds
- rcu
description: Totals over the window.
start_date:
type: string
format: date-time
description: Start of the window that was read.
end_date:
type: string
format: date-time
description: End of the window that was read.
required:
- models
- agents
- machines
- totals
- start_date
- end_date
UsageModelSummary:
type: object
properties:
model:
type: string
description: >-
The model id, without the provider prefix of an own-key model;
`unknown` when none was recorded.
billing:
type: string
enum:
- reason
- own_key
- run_total
description: >-
Who paid: `reason` for calls through Reason's gateway (charged in
RCU), `own_key` for a member's own provider key or sign-in,
`run_total` for runs recorded only as totals.
provider:
description: >-
The provider account that served an own-key model, such as `openai`
(an API key) or `openai-codex` (a ChatGPT sign-in). Null otherwise.
type:
- string
- 'null'
unit:
type: string
enum:
- requests
- runs
description: >-
What `requests` counts: gateway requests (one model call each), or
runs (many model calls each).
requests:
type: number
description: Gateway requests or runs, as `unit` says.
input_tokens:
type: number
description: >-
Input tokens. A run total's input includes its cache reads and
writes.
output_tokens:
type: number
description: Output tokens.
cached_input_tokens:
description: >-
Input tokens read from the provider's cache. Null when only run
totals were recorded.
type:
- number
- 'null'
cache_write_input_tokens:
description: >-
Input tokens written to the provider's cache. Null when only run
totals were recorded.
type:
- number
- 'null'
reasoning_tokens:
description: >-
Reasoning tokens, counted within output. Null when only run totals
were recorded.
type:
- number
- 'null'
total_tokens:
type: number
description: Input plus output tokens.
rcu:
description: >-
RCU charged. Null for usage Reason did not charge for (own key or
run totals).
type:
- number
- 'null'
required:
- model
- billing
- provider
- unit
- requests
- input_tokens
- output_tokens
- cached_input_tokens
- cache_write_input_tokens
- reasoning_tokens
- total_tokens
- rcu
UsageAgentSummary:
type: object
properties:
agent_role:
type: string
enum:
- lead
- helper
description: >-
`lead` for a Session's own agent; `helper` for a subagent another
Session's agent spawned, which runs its own model.
model:
type: string
description: >-
The model id, without the provider prefix of an own-key model;
`unknown` when none was recorded.
billing:
type: string
enum:
- reason
- own_key
- run_total
description: >-
Who paid: `reason` for calls through Reason's gateway (charged in
RCU), `own_key` for a member's own provider key or sign-in,
`run_total` for runs recorded only as totals.
provider:
description: >-
The provider account that served an own-key model, such as `openai`
(an API key) or `openai-codex` (a ChatGPT sign-in). Null otherwise.
type:
- string
- 'null'
unit:
type: string
enum:
- requests
- runs
description: >-
What `requests` counts: gateway requests (one model call each), or
runs (many model calls each).
requests:
type: number
description: Gateway requests or runs, as `unit` says.
input_tokens:
type: number
description: >-
Input tokens. A run total's input includes its cache reads and
writes.
output_tokens:
type: number
description: Output tokens.
cached_input_tokens:
description: >-
Input tokens read from the provider's cache. Null when only run
totals were recorded.
type:
- number
- 'null'
cache_write_input_tokens:
description: >-
Input tokens written to the provider's cache. Null when only run
totals were recorded.
type:
- number
- 'null'
reasoning_tokens:
description: >-
Reasoning tokens, counted within output. Null when only run totals
were recorded.
type:
- number
- 'null'
total_tokens:
type: number
description: Input plus output tokens.
rcu:
description: >-
RCU charged. Null for usage Reason did not charge for (own key or
run totals).
type:
- number
- 'null'
runs:
type: number
description: >-
Distinct runs (Session turns) counted. For helpers, about how many
were spawned.
required:
- agent_role
- model
- billing
- provider
- unit
- requests
- input_tokens
- output_tokens
- cached_input_tokens
- cache_write_input_tokens
- reasoning_tokens
- total_tokens
- rcu
- runs
UsageMachineSummary:
type: object
properties:
rate_id:
description: The machine's RCU rate id, naming its OS and size.
type:
- string
- 'null'
provider:
type: string
description: The compute provider that ran it.
os:
description: Operating system of the rate.
type:
- string
- 'null'
size:
description: Size of the rate.
type:
- string
- 'null'
memory_gb:
description: Memory of the rate, in GB.
type:
- number
- 'null'
machines:
type: number
description: Cloud machines started in the window.
runtime_seconds:
type: number
description: Their running time, in seconds.
rcu:
description: RCU charged for them.
type:
- number
- 'null'
required:
- rate_id
- provider
- os
- size
- memory_gb
- machines
- runtime_seconds
- rcu
Error:
type: object
properties:
error:
oneOf:
- type: string
- type: object
required:
- type
- message
properties:
type:
type: string
message:
type: string
request_id:
type:
- string
- 'null'
message:
type: string
required_scope:
type: string
description: >-
The capability required when the request was denied for a missing
scope.
responses:
Unauthorized:
description: Missing, invalid, or expired key.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error: missing_bearer
message: Authorization required
Forbidden:
description: The key lacks the required scope or role.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error: missing_scope
required_scope: sessions:read
RateLimited:
description: >-
Too many requests. Retry after the number of seconds in the
`Retry-After` response header.
headers:
Retry-After:
description: Seconds to wait before retrying.
schema:
type: integer
minimum: 1
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error:
type: rate_limited
message: This API key exceeded its request-rate limit
securitySchemes:
reasonApiKey:
type: http
scheme: bearer
bearerFormat: 'reason_ (legacy: ara_)'
description: >-
Your Reason API key from Settings › API keys. New keys use `reason_`;
legacy `ara_` keys remain accepted. Keys are capability-scoped: run,
mcp:read, mcp:write, secrets:read, secrets:write, sessions:read,
sessions:debug, knowledge:read, memory:read, memory:write, skills:read,
skills:write, repos:read, repos:write, reviews:read, reviews:write,
deployment:read, analytics:read, org:read, org:write, attachments:read,
attachments:write, guardrails:read, guardrails:write, network:read,
network:write, automations:read, automations:write, agent_auth:read.
network:read and network:write are opt-in, excluded from default keys.
network:read reads the saved workspace network policy; network:write
replaces custom allowed hosts and requires a current organization
owner/admin. Legacy project PATCH requests containing
network_allowed_hosts also require network:write plus their existing run
scope and project management permission; saved project hosts do not
affect current session egress. Only owners/admins can mint or manage
keys with network:write; keys cannot grant themselves more authority.
See /docs/network-policies for replacement semantics and runtime
applicability. mcp:write manages MCP server configuration only; it does
not authorize remote MCP-tool execution. sessions:read reads sessions,
including the assistant, reasoning and tool activity in their events.
sessions:debug is privileged: only for organization owners/admins, it
expands session events to the full diagnostic projection (diagnostic
event kinds, status text and raw event metadata).
````
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.