Get usage

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.

Hosted MCP registration verified. These schemas describe the development contract; confirm supported inputs with tools/list. Generic CLI/HTTP calls require a matching development server. Configure LINKTRAIL_API_URL; production does not expose these command routes.

Access	Behavior
`projects:read`	Reads saved data

Reading saved data does not start a verification job. Mutations can change saved records or access; the effects below apply.

Example request

Connect through MCP, CLI, or HTTP. Replace example identifiers with records from your workspace.

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "get_usage",
    "arguments": {}
  }
}

linktrail call get_usage --args '{}'

curl "$LINKTRAIL_API_URL/v1/commands/get_usage" \
  -H "Authorization: Bearer $LINKTRAIL_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.

{
  "workspace_id": "ws_example",
  "period": "2026-09",
  "plan": "free",
  "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": 300,
      "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 explain evidence states, empty lists and extensions.

Field	Type	Presence	Meaning and constraints
`workspace_id`	string	Required	Workspace that owns this record.
`period`	string	Required	period recorded for this result.
`plan`	string	Required	plan recorded for this result.
`subscription_status`	string	Required	subscription status recorded for this result.
`check_reservations`	object	Required	check reservations recorded for this result.
`check_reservations.reserved`	number	Required	reserved recorded for this result.
`check_reservations.consumed`	number	Required	consumed recorded for this result.
`check_reservations.released`	number	Required	released recorded for this result.
`check_reservations.note`	string	Required	note recorded for this result.
`monthly_check_limit`	number / null	Required	monthly check limit recorded for this result.
`check_budget`	object	Required	check budget recorded for this result.
`check_budget.period`	string	Required	period recorded for this result.
`check_budget.limit`	number / null	Required	limit recorded for this result.
`check_budget.reserved`	number	Required	reserved recorded for this result.
`check_budget.consumed`	number	Required	consumed recorded for this result.
`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	exhausted recorded for this result.
`check_budget.resets_at`	string	Required	resets at recorded for this result.
`check_budget.enforced_by`	string	Required	enforced by recorded for this result.
`check_budget.plan_allowance_enforced`	boolean	Required	plan allowance enforced recorded for this result.
`active_watch_limit`	number / null	Required	active watch limit recorded for this result.
`units`	object	Required	units recorded for this result.
`units.{property}.used`	number	Required	used recorded for this result.
`units.{property}.included_allowance`	number	Required	included allowance recorded for this result.
`units.{property}.included_used`	number	Required	included used recorded for this result.
`units.{property}.chargeable`	number	Required	chargeable recorded for this result.
`units.{property}.rate_microusd_per_1000`	number	Required	rate microusd per 1000 recorded for this result.
`units.{property}.chargeable_microusd`	number	Required	chargeable microusd recorded for this result.
`chargeable_microusd`	number	Required	chargeable microusd recorded for this result.
`pricing_mode`	string	Required	pricing mode recorded for this result. must equal “estimate_only”
`at_allowance`	object	Required	at allowance recorded for this result.
`at_allowance.at_allowance`	string	Required	at allowance recorded for this result.
`at_allowance.enforced_limit`	string	Required	enforced limit recorded for this result.
`at_allowance.note`	string	Required	note recorded for this result.
`checkout`	object	Required	checkout recorded for this result.
`checkout.available`	boolean	Required	available recorded for this result.
`checkout.reason`	string / null	Required	Recorded explanation; null when no explanation applies.
`collected`	boolean	Required	collected recorded for this result. must equal false

Download input schema · Download output schema

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 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.

Method and route	Success	Details
`GET /v1/usage`	200	Remaining read arguments go in query parameters.

Continue

get_workspace Follow the related workflow, inspect capability status, or return to the command index.

Overview

Cloud operations

Repository tools

HTTP and events

Example request

Returned result

Input fields

Validation and omitted values

Output fields

Errors and retries

HTTP resource routes

Continue

​Example request

​Returned result

​Input fields

​Validation and omitted values

​Output fields

​Errors and retries

​HTTP resource routes

​Continue

Example request

Returned result

Input fields

Validation and omitted values

Output fields

Errors and retries

HTTP resource routes

Continue