Get Usage Stats
curl --request GET \
--url https://api.shoal.xyz/v1/usage \
--header 'Authorization: Bearer <token>'import requests
url = "https://api.shoal.xyz/v1/usage"
headers = {"Authorization": "Bearer <token>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
fetch('https://api.shoal.xyz/v1/usage', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.shoal.xyz/v1/usage",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.shoal.xyz/v1/usage"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("Authorization", "Bearer <token>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://api.shoal.xyz/v1/usage")
.header("Authorization", "Bearer <token>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.shoal.xyz/v1/usage")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'
response = http.request(request)
puts response.read_bodyCore
Get Usage Stats
Get request usage statistics and budget info for your API key
GET
/
v1
/
usage
Get Usage Stats
curl --request GET \
--url https://api.shoal.xyz/v1/usage \
--header 'Authorization: Bearer <token>'import requests
url = "https://api.shoal.xyz/v1/usage"
headers = {"Authorization": "Bearer <token>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
fetch('https://api.shoal.xyz/v1/usage', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.shoal.xyz/v1/usage",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.shoal.xyz/v1/usage"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("Authorization", "Bearer <token>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://api.shoal.xyz/v1/usage")
.header("Authorization", "Bearer <token>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.shoal.xyz/v1/usage")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'
response = http.request(request)
puts response.read_bodyReturns 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-TierX-Api-SurfaceX-Access-LayerX-Endpoint-PolicyX-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
}
}
}
| Field | Description |
|---|---|
today | Requests made since midnight UTC today |
thisWeek | Requests made since the start of the current week |
thisMonth | Requests made since the start of the current month |
budget.limit | Monthly credit budget for the API key |
budget.used | Credits consumed so far this month |
budget.remaining | Credits 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.