Get usage
GET https://api.companylens.io/api/v1/usageReturns your current plan tier, rate limits, and usage for the active billing period, broken down by product (api and mcp). Use this endpoint to check how many requests you have remaining before hitting your daily or monthly cap, or to display plan information to your users.
This endpoint is free — it does not consume any of your quota.
Request
Authentication
Authorization: Bearer YOUR_API_KEYNo query parameters. The response reflects the plan associated with the API key you authenticate with.
Examples
curl
curl https://api.companylens.io/api/v1/usage \
-H "Authorization: Bearer YOUR_API_KEY"Node.js
const res = await fetch(
'https://api.companylens.io/api/v1/usage',
{ headers: { Authorization: 'Bearer YOUR_API_KEY' } }
);
const { data } = await res.json();
console.log(`API: ${data.api.used} / ${data.api.limit ?? '∞'} requests used`);
console.log(`MCP: ${data.mcp.used} / ${data.mcp.limit ?? '∞'} tool calls used`);Python
import httpx
r = httpx.get(
'https://api.companylens.io/api/v1/usage',
headers={'Authorization': 'Bearer YOUR_API_KEY'},
)
data = r.json()['data']
print(f"API: {data['api']['used']} / {data['api']['limit'] or '∞'} requests used")
print(f"MCP: {data['mcp']['used']} / {data['mcp']['limit'] or '∞'} tool calls used")Response
200 — Success
The response is keyed by product. Both api and mcp are always present.
{
"data": {
"api": {
"tierId": "developer",
"displayName": "API Starter",
"status": "active",
"limitType": "monthly",
"dailyLimit": null,
"monthlyLimit": 5000,
"used": 1234,
"limit": 5000,
"remaining": 3766,
"resetAt": "2026-05-01T00:00:00Z",
"currentPeriodEnd": "2026-05-06T00:00:00Z",
"trialEndsAt": null
},
"mcp": {
"tierId": "mcp_pro",
"displayName": "MCP Pro",
"status": "active",
"limitType": "daily",
"dailyLimit": 2000,
"monthlyLimit": null,
"used": 47,
"limit": 2000,
"remaining": 1953,
"resetAt": "2026-04-09T00:00:00Z",
"currentPeriodEnd": "2026-05-06T00:00:00Z",
"trialEndsAt": null
}
},
"meta": {
"requestId": "a1b2c3d4e5f6"
}
}Free-tier example
Free tiers enforce a daily cap. limitType is daily and usedreflects today's count.
{
"data": {
"api": {
"tierId": "free_api",
"displayName": "Free",
"status": "none",
"limitType": "daily",
"dailyLimit": 50,
"monthlyLimit": null,
"used": 12,
"limit": 50,
"remaining": 38,
"resetAt": "2026-04-09T00:00:00Z",
"currentPeriodEnd": null,
"trialEndsAt": null
},
"mcp": {
"tierId": "free_mcp",
"displayName": "Free",
"status": "none",
"limitType": "daily",
"dailyLimit": 50,
"monthlyLimit": null,
"used": 5,
"limit": 50,
"remaining": 45,
"resetAt": "2026-04-09T00:00:00Z",
"currentPeriodEnd": null,
"trialEndsAt": null
}
}
}Response fields
Each product key (api, mcp) contains the following fields:
| Field | Type | Description |
|---|---|---|
| tierId | string | Internal tier identifier, e.g. free_api, developer, mcp_pro. |
| displayName | string | Human-readable tier name. |
| status | string | Subscription status: none, active, trialing, past_due, canceled, etc. |
| limitType | "daily" | "monthly" | Which quota window is the binding constraint. Free tiers are daily; paid tiers are monthly. |
| dailyLimit | number | null | Daily request cap. null if the plan has no daily limit. |
| monthlyLimit | number | null | Monthly request cap. null if the plan has no monthly limit. |
| used | number | Requests consumed in the active window (today if limitType: daily, this calendar month if monthly). |
| limit | number | null | The binding cap for the active window. null for unlimited plans. |
| remaining | number | null | Requests left in the current window (limit - used, floored at 0). null for unlimited plans. |
| resetAt | string | ISO 8601 timestamp when the active quota window resets (midnight UTC for daily; first of next month for monthly). |
| currentPeriodEnd | string | null | ISO 8601 timestamp when the current billing period ends. null for free plans. |
| trialEndsAt | string | null | ISO 8601 timestamp when the trial ends. null if not on a trial. |
Error responses
| HTTP status | Code | When it happens |
|---|---|---|
| 401 | UNAUTHORIZED | Missing or invalid API key |