> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agentlinkops.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Get usage
> Read workspace usage, allowance and billing availability for one UTC month.
`get_usage`
Read workspace usage, allowance and billing availability for one UTC month. Source and destination checks share allowance; reserved, consumed and released are separate totals.
Available in the deployed MCP and HTTP bundle. Confirm access and inputs with your connected catalog. Workspace scopes and enabled providers still apply.
| Access | Behavior |
| --------------- | ---------------- |
| `projects:read` | Reads saved data |
This read does not start a verification job.
## Example request
Connect through [MCP](/guides/connect-mcp), [CLI](/guides/connect-cli), or [HTTP](/guides/connect-http). Replace example identifiers with records from your workspace.
```json MCP theme={null}
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "get_usage",
"arguments": {}
}
}
```
```bash CLI theme={null}
agentlinkops call get_usage --args '{}'
```
```bash HTTP theme={null}
curl "$AGENTLINKOPS_API_URL/v1/commands/get_usage" \
-H "Authorization: Bearer $AGENTLINKOPS_API_KEY" \
-H 'Content-Type: application/json' \
--data '{}'
```
## Returned result
Illustrative data validated against the documented response schema. IDs and dates are examples, not a live account capture. MCP returns this data in `structuredContent` and in a text content block; generic HTTP and CLI return the JSON result directly.
```json theme={null}
{
"workspace_id": "ws_example",
"period": "2026-09",
"plan": "none",
"subscription_status": "none",
"check_reservations": {
"reserved": 0,
"consumed": 0,
"released": 0,
"note": "Reserved is in flight and may still be released. Only consumed is a check that happened."
},
"monthly_check_limit": 3500,
"check_budget": {
"period": "2026-09",
"limit": 3500,
"reserved": 0,
"consumed": 0,
"remaining": 3500,
"exhausted": false,
"resets_at": "2026-10-01T00:00:00.000Z",
"enforced_by": "workspace_monthly_check_limit",
"plan_allowance_enforced": false
},
"active_watch_limit": 100,
"units": {
"check": {
"used": 0,
"included_allowance": 0,
"included_used": 0,
"chargeable": 0,
"rate_microusd_per_1000": 250000,
"chargeable_microusd": 0
},
"render": {
"used": 0,
"included_allowance": 0,
"included_used": 0,
"chargeable": 0,
"rate_microusd_per_1000": 2000000,
"chargeable_microusd": 0
},
"crawl_page": {
"used": 0,
"included_allowance": 0,
"included_used": 0,
"chargeable": 0,
"rate_microusd_per_1000": 1000000,
"chargeable_microusd": 0
},
"crawl_page_proxied_surcharge": {
"used": 0,
"included_allowance": 0,
"included_used": 0,
"chargeable": 0,
"rate_microusd_per_1000": 1000000,
"chargeable_microusd": 0
}
},
"chargeable_microusd": 0,
"pricing_mode": "estimate_only",
"at_allowance": {
"at_allowance": "hard_stop",
"enforced_limit": "workspace_monthly_check_limit",
"note": "New checks stop when consumed and reserved checks reach the workspace monthly limit. Released reservations free capacity; the monthly limit resets next UTC month. Plan allowances are used only for billing estimates. Nothing is charged."
},
"checkout": {
"available": false,
"reason": "Payment collection is not enabled in this build."
},
"collected": false
}
```
## Input fields
Omit optional fields when you do not want to supply them. Null is accepted only where listed. Unknown input properties are rejected.
| Field | Type | Presence | Meaning and constraints |
| -------- | ------ | -------- | --------------------------------------------------------------------------------------------------- |
| `period` | string | Optional | Billing month in UTC, formatted YYYY-MM; defaults to the current month. pattern: "^\d\{4}-\d\{2}\$" |
### Validation and omitted values
Omitting period uses the current UTC month in YYYY-MM format. Source and destination checks share allowance; reserved, consumed and released are distinct.
## Output fields
Fields inside optional or nullable parents apply only when that parent exists. [Common schema conventions](/reference/schemas) explain evidence states, empty lists and extensions.
* **`workspace_id`** (string, required): Workspace that owns this record.
* **`period`** (string, required).
* **`plan`** (string, required).
* **`subscription_status`** (string, required).
* **`check_reservations`** (object, required).
* **`monthly_check_limit`** (number / null, required).
* **`check_budget`** (object, required).
* **`active_watch_limit`** (number / null, required).
* **`units`** (object, required).
* **`chargeable_microusd`** (number, required).
* **`pricing_mode`** (string, required): must equal "estimate\_only"
* **`at_allowance`** (object, required).
* **`checkout`** (object, required).
* **`collected`** (boolean, required): must equal false
| Field | Type | Presence | Meaning and constraints |
| --------------------------------------------------- | -------------- | -------- | -------------------------------------------------------------------------------------------- |
| `workspace_id` | string | Required | Workspace that owns this record. |
| `period` | string | Required | |
| `plan` | string | Required | |
| `subscription_status` | string | Required | |
| `check_reservations` | object | Required | |
| `check_reservations.reserved` | number | Required | |
| `check_reservations.consumed` | number | Required | |
| `check_reservations.released` | number | Required | |
| `check_reservations.note` | string | Required | |
| `monthly_check_limit` | number / null | Required | |
| `check_budget` | object | Required | |
| `check_budget.period` | string | Required | |
| `check_budget.limit` | number / null | Required | |
| `check_budget.reserved` | number | Required | |
| `check_budget.consumed` | number | Required | |
| `check_budget.remaining` | number / null | Required | Check units still available after consumed and reserved units; null if the limit is unknown. |
| `check_budget.exhausted` | boolean / null | Required | |
| `check_budget.resets_at` | string | Required | |
| `check_budget.enforced_by` | string | Required | |
| `check_budget.plan_allowance_enforced` | boolean | Required | |
| `active_watch_limit` | number / null | Required | |
| `units` | object | Required | |
| `units.{property}.used` | number | Required | |
| `units.{property}.included_allowance` | number | Required | |
| `units.{property}.included_used` | number | Required | |
| `units.{property}.chargeable` | number | Required | |
| `units.{property}.rate_microusd_per_1000` | number | Required | |
| `units.{property}.chargeable_microusd` | number | Required | |
| `chargeable_microusd` | number | Required | |
| `pricing_mode` | string | Required | must equal "estimate\_only" |
| `at_allowance` | object | Required | |
| `at_allowance.at_allowance` | string | Required | |
| `at_allowance.enforced_limit` | string | Required | |
| `at_allowance.note` | string | Required | |
| `checkout` | object | Required | |
| `checkout.available` | boolean | Required | |
| `checkout.reason` | string / null | Required | Recorded explanation; null when no explanation applies. |
| `collected` | boolean | Required | must equal false |
[Download input schema](/schemas/get_usage.input.json) · [Download output schema](/schemas/get_usage.output.json)
## Errors and retries
The command is annotated idempotent. Reuse an accepted idempotency key when the input provides one; changing the payload under a reused key can conflict.
See [error recovery](/reference/errors) for status, scope, cooldown, cursor and retry handling. Unknown observations are result data and do not establish loss.
## HTTP resource routes
These existing resource routes share the operation’s domain behavior. Their parameter placement, status and response envelope can differ from generic invocation. See [HTTP route details](/reference/http/routes).
| Method and route | Success | Details |
| ---------------- | ------- | ------------------------------------------------ |
| `GET /v1/usage` | 200 | Remaining read arguments go in query parameters. |
## Continue
[get\_workspace](/reference/commands/get_workspace)
Follow the [related workflow](/guides/connect-http), inspect [capability status](/capability-status), or return to the [command index](/reference/index).