Skip to main content
GET
/
v1
/
usage
Get Usage Stats
curl --request GET \
  --url https://api.shoal.xyz/v1/usage \
  --header 'Authorization: Bearer <token>'

Documentation Index

Fetch the complete documentation index at: https://docs.shoal.xyz/llms.txt

Use this file to discover all available pages before exploring further.

Returns your API key’s request counts and monthly credit consumption. Use this to monitor how close you are to your credit limit, track usage trends, or build self-budgeting logic into your integration. This endpoint does not consume monthly credit budget. This route is also the safest place to inspect the packaging metadata attached to your key and request path. The response headers include:
  • X-Plan-Tier
  • X-Api-Surface
  • X-Access-Layer
  • X-Endpoint-Policy
  • X-Credit-Cost

​
Query Parameters

None. Usage is determined by the API key in your Authorization header.

​
Request

cURL
curl -X GET "https://api.shoal.xyz/v1/usage" \
  -H "Authorization: Bearer YOUR_API_KEY"

​
Response (200)

{
  "data": {
    "today": 42,
    "thisWeek": 310,
    "thisMonth": 1205,
    "budget": {
      "limit": 1000,
      "used": 420,
      "remaining": 580
    }
  }
}
FieldDescription
todayRequests made since midnight UTC today
thisWeekRequests made since the start of the current week
thisMonthRequests made since the start of the current month
budget.limitMonthly credit budget for the API key
budget.usedCredits consumed so far this month
budget.remainingCredits remaining for the current month
The request counters (today, thisWeek, thisMonth) track request volume. The budget object tracks monthly credit consumption.
/v1/usage itself is an evaluation-layer usage surface and does not consume monthly credits.