Xagent Docs
Get started

Usage & Quotas

Every team has quota limits set by its plan. Xagent meters usage against those limits and enforces them as you create agents and run tasks.

What Is Metered

MetricCountsResets?
actions_per_monthEvery step an agent takes — each tool call or step counts as one.Monthly
ai_credits_per_monthModel usage. Steps that call a built-in model draw credits; your own model keys never do.Monthly
max_usersTeam seats currently filled.No — live count
kb_storage_gbTotal size of team knowledge base content.No — live measurement
max_agentsNumber of agents. Currently unlimited on every sellable plan.No — live count

Metrics you may not see

agent_executions_per_month exists but is switched off by default, so it does not appear in your usage. Metrics that are unlimited on your plan are omitted from the response rather than shown as unlimited.

Checking Usage

Read current usage and remaining allowance for your team. Each metric reports used against its limit, where -1 means unlimited:

GET /api/billing/usage
{
  "actions_per_month": { "used": 1240, "limit": 5000 },
  "ai_credits_per_month": { "used": 3180, "limit": 10000 },
  "max_users": { "used": 2, "limit": 2 },
  "kb_storage_gb": { "used": 0.8, "limit": 3 }
}

When You Hit a Limit

Once an allowance is used up, further work of that kind is refused until the next reset or until you upgrade. The API responds with 402 Payment Required and a structured body naming the metric and your plan:

HTTP/1.1 402 Payment Required
{
  "code": "quota_exceeded",
  "plan": "pro",
  "message": "Plan limit reached: actions_per_month (5000/5000)"
}

Two situations produce a 402 that people find surprising:

SituationWhat happens
Accepting a team invitationIf the team is already at its seat limit, the invitee gets the 402. Only an admin can free a seat or upgrade.
Uploading to a knowledge baseOnce team storage is full, uploads are refused with a message asking you to upgrade. Deleting files frees space straight away.

Partner integrations have their own share

If your organisation runs a partner integration, an individual application can have its own slice of the team allowance. When that slice runs out you get client_quota_exceeded instead of quota_exceeded, even though the team still has headroom.

If your subscription lapses

A team with no active paid plan falls back to a state with zero allowance, so agents stop running until a plan is active again. Your agents, knowledge bases and history are not deleted.

Next Steps