Usage & Quotas

The usage API provides information about your credit consumption, message history, and per-agent analytics. All endpoints require authentication.

Usage Summary

GET /usage

Get an overview of your current usage and quota limits.

Response:

{
  "credits_used": 1250.5,
  "credits_limit": 5000.0,
  "rolling_window_days": 30,
  "agent_count": 3,
  "agent_limit": 5,
  "tier": "free"
}

Field	Type	Description
credits_used	float	Credits consumed in the current rolling window
credits_limit	float	Maximum credits allowed in the rolling window
rolling_window_days	integer	Length of the rolling window in days
agent_count	integer	Number of agents you currently have
agent_limit	integer	Maximum agents allowed for your tier
tier	string	Your account tier (e.g., guest, free, pro)

curl:

curl https://api.liberclaw.ai/api/v1/usage \
  -H "Authorization: Bearer <access_token>"

JavaScript:

const res = await fetch("https://api.liberclaw.ai/api/v1/usage", {
  headers: { Authorization: `Bearer ${accessToken}` },
});
const usage = await res.json();
console.log(`Credits: ${usage.credits_used} / ${usage.credits_limit}`);

---

Usage History

GET /usage/history

Get a daily breakdown of message counts.

Query parameters:

Parameter	Type	Default	Range	Description
days	integer	30	1-90	Number of days of history

Response:

{
  "days": [
    { "date": "2026-01-15", "message_count": 42 },
    { "date": "2026-01-14", "message_count": 18 },
    { "date": "2026-01-13", "message_count": 7 }
  ]
}

curl:

curl "https://api.liberclaw.ai/api/v1/usage/history?days=7" \
  -H "Authorization: Bearer <access_token>"

JavaScript:

const res = await fetch(
  "https://api.liberclaw.ai/api/v1/usage/history?days=7",
  { headers: { Authorization: `Bearer ${accessToken}` } }
);
const { days } = await res.json();

---

Per-Agent Usage

GET /usage/per-agent

Get message counts and token usage broken down by agent.

Query parameters:

Parameter	Type	Default	Range	Description
days	integer	30	1-90	Number of days to aggregate

Response:

{
  "agents": [
    {
      "agent_id": "550e8400-e29b-41d4-a716-446655440000",
      "agent_name": "Research Assistant",
      "message_count": 156,
      "total_tokens": 245000
    },
    {
      "agent_id": "660e8400-e29b-41d4-a716-446655440001",
      "agent_name": "Code Helper",
      "message_count": 42,
      "total_tokens": 89000
    }
  ],
  "period_days": 30
}

Field	Type	Description
agent_id	string or null	Agent UUID (null if the agent was deleted)
agent_name	string	Agent name at the time of the request
message_count	integer	Total messages sent to this agent
total_tokens	integer	Total tokens consumed by this agent
period_days	integer	The time period these stats cover

curl:

curl "https://api.liberclaw.ai/api/v1/usage/per-agent?days=7" \
  -H "Authorization: Bearer <access_token>"

JavaScript:

const res = await fetch(
  "https://api.liberclaw.ai/api/v1/usage/per-agent?days=30",
  { headers: { Authorization: `Bearer ${accessToken}` } }
);
const { agents, period_days } = await res.json();
for (const agent of agents) {
  console.log(`${agent.agent_name}: ${agent.message_count} messages`);
}