/v1/usage/report endpoint. The report includes token consumption, request counts, and costs for each day in the requested period.
GET /v1/usage/report is not yet live on the production API — it exists only on an unmerged feature branch. Calling it against https://api.swarms.world will currently return a 404. For live per-operation pricing, use /v1/usage/costs instead.The endpoint supports predefined periods (
day, week, month) and custom date ranges via start_date and end_date query parameters. See the API Reference for the full schema.Quick Start
- Python
- JavaScript
- TypeScript
- Rust
- Go
- cURL
import os
import json
import requests
from dotenv import load_dotenv
load_dotenv()
API_KEY = os.getenv("SWARMS_API_KEY")
BASE_URL = "https://api.swarms.world"
headers = {
"x-api-key": API_KEY,
"Content-Type": "application/json",
}
def get_usage_report(period: str = "month") -> dict | None:
"""Fetch a daily usage report for the given period."""
resp = requests.get(
f"{BASE_URL}/v1/usage/report",
headers=headers,
params={"period": period},
)
if resp.status_code == 200:
return resp.json()
print(f"Error: {resp.status_code} - {resp.text}")
return None
if __name__ == "__main__":
data = get_usage_report("week")
if data:
print(f"Period: {data['period']}")
print(f"Range: {data['start_date']} to {data['end_date']}")
print(f"Days with activity: {len(data['results'])}\n")
for day in data["results"]:
print(
f" {day['day']}: "
f"cost=${day['total_cost']:.4f}, "
f"in={day['input_tokens']:,}, "
f"out={day['output_tokens']:,}, "
f"reqs={day['request_count']}"
)
const API_KEY = process.env.SWARMS_API_KEY;
const BASE_URL = "https://api.swarms.world";
const headers = {
"x-api-key": API_KEY,
"Content-Type": "application/json"
};
async function getUsageReport(period = "month") {
try {
const response = await fetch(
`${BASE_URL}/v1/usage/report?period=${period}`,
{ method: "GET", headers }
);
if (!response.ok) {
throw new Error(`HTTP error! status: ${response.status}`);
}
const data = await response.json();
console.log(`Period: ${data.period}`);
console.log(`Range: ${data.start_date} to ${data.end_date}`);
console.log(`Days with activity: ${data.results.length}\n`);
for (const day of data.results) {
console.log(
` ${day.day}: ` +
`cost=$${day.total_cost.toFixed(4)}, ` +
`in=${day.input_tokens.toLocaleString()}, ` +
`out=${day.output_tokens.toLocaleString()}, ` +
`reqs=${day.request_count}`
);
}
return data;
} catch (error) {
console.error("Error fetching usage report:", error);
return null;
}
}
getUsageReport("week");
import "dotenv/config";
const API_KEY = process.env.SWARMS_API_KEY;
const BASE_URL = "https://api.swarms.world";
if (!API_KEY) {
throw new Error("SWARMS_API_KEY is not set");
}
interface UsageReportDay {
day: string;
total_cost: number;
input_tokens: number;
output_tokens: number;
request_count: number;
}
interface UsageReportOutput {
results: UsageReportDay[];
period: string;
start_date: string;
end_date: string;
timestamp: string;
}
async function getUsageReport(
period: string = "month"
): Promise<UsageReportOutput | null> {
const res = await fetch(
`${BASE_URL}/v1/usage/report?period=${period}`,
{
method: "GET",
headers: {
"x-api-key": API_KEY,
"Content-Type": "application/json",
},
}
);
if (!res.ok) {
const text = await res.text();
throw new Error(`HTTP ${res.status}: ${text}`);
}
const data = (await res.json()) as UsageReportOutput;
console.log(`Period: ${data.period}`);
console.log(`Range: ${data.start_date} to ${data.end_date}`);
console.log(`Days with activity: ${data.results.length}\n`);
for (const day of data.results) {
console.log(
` ${day.day}: cost=$${day.total_cost.toFixed(4)}, ` +
`in=${day.input_tokens.toLocaleString()}, ` +
`out=${day.output_tokens.toLocaleString()}, ` +
`reqs=${day.request_count}`
);
}
return data;
}
void getUsageReport("week").catch(console.error);
use std::env;
use reqwest::blocking::Client;
use serde::Deserialize;
#[derive(Debug, Deserialize)]
struct UsageReportDay {
day: String,
total_cost: f64,
input_tokens: u64,
output_tokens: u64,
request_count: u64,
}
#[derive(Debug, Deserialize)]
struct UsageReportOutput {
results: Vec<UsageReportDay>,
period: String,
start_date: String,
end_date: String,
timestamp: String,
}
fn main() -> Result<(), Box<dyn std::error::Error>> {
let api_key = env::var("SWARMS_API_KEY")
.expect("SWARMS_API_KEY environment variable is required");
let client = Client::new();
let response = client
.get("https://api.swarms.world/v1/usage/report?period=week")
.header("x-api-key", &api_key)
.header("Content-Type", "application/json")
.send()?;
let data: UsageReportOutput = response.json()?;
println!("Period: {}", data.period);
println!("Range: {} to {}", data.start_date, data.end_date);
println!("Days with activity: {}\n", data.results.len());
for day in &data.results {
println!(
" {}: cost=${:.4}, in={}, out={}, reqs={}",
day.day, day.total_cost, day.input_tokens,
day.output_tokens, day.request_count,
);
}
Ok(())
}
package main
import (
"encoding/json"
"fmt"
"log"
"net/http"
"os"
)
type UsageReportDay struct {
Day string `json:"day"`
TotalCost float64 `json:"total_cost"`
InputTokens int `json:"input_tokens"`
OutputTokens int `json:"output_tokens"`
RequestCount int `json:"request_count"`
}
type UsageReportOutput struct {
Results []UsageReportDay `json:"results"`
Period string `json:"period"`
StartDate string `json:"start_date"`
EndDate string `json:"end_date"`
Timestamp string `json:"timestamp"`
}
func main() {
apiKey := os.Getenv("SWARMS_API_KEY")
if apiKey == "" {
log.Fatal("SWARMS_API_KEY environment variable is required")
}
req, err := http.NewRequest("GET", "https://api.swarms.world/v1/usage/report?period=week", nil)
if err != nil {
log.Fatal(err)
}
req.Header.Set("x-api-key", apiKey)
req.Header.Set("Content-Type", "application/json")
resp, err := http.DefaultClient.Do(req)
if err != nil {
log.Fatal(err)
}
defer resp.Body.Close()
var data UsageReportOutput
if err := json.NewDecoder(resp.Body).Decode(&data); err != nil {
log.Fatal(err)
}
fmt.Printf("Period: %s\n", data.Period)
fmt.Printf("Range: %s to %s\n", data.StartDate, data.EndDate)
fmt.Printf("Days with activity: %d\n\n", len(data.Results))
for _, day := range data.Results {
fmt.Printf(" %s: cost=$%.4f, in=%d, out=%d, reqs=%d\n",
day.Day, day.TotalCost, day.InputTokens,
day.OutputTokens, day.RequestCount,
)
}
}
# Last 30 days (default)
curl -X GET "https://api.swarms.world/v1/usage/report" \
-H "x-api-key: $SWARMS_API_KEY"
# Last 7 days
curl -X GET "https://api.swarms.world/v1/usage/report?period=week" \
-H "x-api-key: $SWARMS_API_KEY"
# Custom date range
curl -X GET "https://api.swarms.world/v1/usage/report?start_date=2026-03-01&end_date=2026-03-31" \
-H "x-api-key: $SWARMS_API_KEY"
Custom Date Range
Passstart_date and end_date as query parameters to query a specific window. These override the period parameter.
def get_usage_for_march():
"""Fetch usage for a specific month."""
resp = requests.get(
f"{BASE_URL}/v1/usage/report",
headers=headers,
params={
"start_date": "2026-03-01",
"end_date": "2026-03-31",
},
)
data = resp.json()
total_cost = sum(d["total_cost"] for d in data["results"])
total_reqs = sum(d["request_count"] for d in data["results"])
print(f"March 2026: ${total_cost:.2f} across {total_reqs:,} requests")
Monitor Usage Over Time
Build a simple cost tracker that alerts on high-usage days:def check_daily_spend(threshold: float = 5.0):
"""Alert if any day in the past week exceeded a cost threshold."""
data = get_usage_report("week")
if not data:
return
for day in data["results"]:
if day["total_cost"] > threshold:
print(
f"High spend on {day['day']}: "
f"${day['total_cost']:.2f} "
f"({day['request_count']} requests)"
)
check_daily_spend(threshold=2.0)
Response Schema
UsageReportOutput
| Field | Type | Description |
|---|---|---|
results | list | Daily usage entries, sorted ascending by date |
period | string | The period applied: day, week, month, or custom |
start_date | string | Report start date (YYYY-MM-DD) |
end_date | string | Report end date (YYYY-MM-DD) |
timestamp | string | ISO timestamp when the report was generated |
UsageReportDay
| Field | Type | Description |
|---|---|---|
day | string | Date (YYYY-MM-DD) |
total_cost | number | Total cost in USD |
input_tokens | integer | Total input tokens consumed |
output_tokens | integer | Total output tokens consumed |
request_count | integer | Total API requests |
Related Documentation
- Usage Report API Reference — full endpoint specification
- Get Credit Balance — check your current balance
- Pricing Details — per-operation costs
- Rate Limits — rate limit status