AI credits through REST API and MCP

AI credits pay for the AI features of AxiTrace, such as AI Advisor reports. Through the API and MCP you can read the balance of your account, where the credits came from, what expires soon and every credit spent and added. Every surface returns the same numbers as the AI credits page of the admin panel, from the same calculation. How credits work is explained in AI credits.

Access

Both endpoints and the tool need the ai_credits:read scope and a paid plan. The scope is read-only and returns no personal data and no payment details, so it is part of the default set: connections and personal access tokens made before it existed received it automatically, without reconnecting. Credits are bought only in the admin panel, never through the API. Authentication, envelopes, errors and rate limits follow the REST API v1 reference; full schemas are in the OpenAPI document.

The wallet belongs to your account, not to one workspace: every workspace of the account answers the same wallet. Pass workspace_id as a query parameter when the token covers several workspaces; it only selects the account. Times are in UTC.

Operations

Balance

curl -H "Authorization: Bearer $TOKEN" \
  "https://axitrace.com/api/v1/ai-credits"

{
  "data": {
    "available": 32418,
    "reserved": 600,
    "debt": 0,
    "state": "ok",
    "by_source": { "plan": 29018, "purchased": 0, "trial": 0, "signup": 3000, "manual": 0, "refunded": 0 },
    "expiring_soon": { "credits": 0, "until": "2026-12-04T10:00:00+00:00" },
    "used_this_period": 982,
    "monthly_allowance": 30000,
    "next_grant_at": "2026-12-15T00:00:00+00:00"
  },
  "meta": { "workspace_id": "7a2b3c4d-0000-4000-8000-000000000011", "range": null, "currency": null, "freshness": null, "total_count": null, "generated_at": "2026-11-20T10:00:00+00:00" },
  "links": { "next": null }
}

• available is what can be spent now: the valid credits minus reserved minus debt. It can be negative while a debt is larger than the credits left.
• reserved is held by AI actions in progress. An AI Advisor report reserves 600 credits and is then charged its actual cost, usually 380 to 600 credits.
• debt appears when an action that was already running cost more than was left. It is repaid first from the next credits granted.
• state is low below 20% of the monthly allowance and empty at 0 or below.
• by_source splits the valid credits into plan, purchased, trial, signup (the one-off welcome credits) manual (added by AxiTrace support) and refunded (given back for an AI Advisor report that was charged but failed).
• used_this_period is the credits charged in the current billing period, net of the refunds of failed reports.

Activity

curl -H "Authorization: Bearer $TOKEN" \
  "https://axitrace.com/api/v1/ai-credits/activity?limit=2"

{
  "data": {
    "activity": [
      { "id": 41, "occurred_at": "2026-11-20T09:58:12+00:00", "kind": "usage", "feature": "ai_advisor", "description": "AI Advisor report", "credits": -382, "balance_after": 32418 },
      { "id": 37, "occurred_at": "2026-11-15T00:04:00+00:00", "kind": "plan_grant", "feature": null, "description": "Monthly plan credits", "credits": 30000, "balance_after": 33400 }
    ]
  },
  "links": { "next": "https://axitrace.com/api/v1/ai-credits/activity?limit=2&cursor=..." }
}

kind is one of usage, usage_refund (credits given back for an AI Advisor report that was charged but failed), signup_grant, plan_grant, trial_grant, purchase_grant, manual_credit, manual_debit, dispute_regrant, expired, clawback (credits taken back after a refund or payment dispute) and debt_repayment. One AI action is one row even when it took credits from several grants. Reservations of an action in progress are not listed: the row appears when the action is charged. credits is negative when credits were spent or removed; balance_after is the available balance after the row.

Errors

• 403 insufficient_scope: the token does not carry ai_credits:read.
• 403 plan_required: the workspace is on the Free plan, which does not include the API.
• 400 invalid_request: workspace_id is missing on a token that covers several workspaces, the cursor was edited, or limit is outside 1 to 100.