> ## Documentation Index > Fetch the complete documentation index at: https://docs.swarms.ai/llms.txt > Use this file to discover all available pages before exploring further. # Usage Report > API reference for the GET /v1/usage/report endpoint — retrieve daily usage breakdowns including token counts, request counts, and costs. The Usage Report endpoint returns a daily breakdown of your API usage for a given time period. It aggregates data from request history, giving you visibility into token consumption, request volume, and costs. ## Endpoint Information * **URL**: `/v1/usage/report` * **Method**: `GET` * **Authentication**: Required (`x-api-key` header or `Authorization: Bearer `) * **Rate Limiting**: Subject to tier-based rate limits *** ## Query Parameters | Parameter | Type | Required | Default | Description | | ------------ | -------- | -------- | ------- | --------------------------------------------------------------------------------------------------------------------- | | `period` | `string` | No | `month` | Predefined time window: `day` (last 24 hours), `week` (last 7 days), or `month` (last 30 days) | | `start_date` | `string` | No | — | Custom range start in `YYYY-MM-DD` format. When both `start_date` and `end_date` are provided, they override `period` | | `end_date` | `string` | No | — | Custom range end in `YYYY-MM-DD` format. Required when `start_date` is set | Custom date ranges take precedence over the `period` parameter. If you pass both `start_date`/`end_date` and `period`, the custom range is used. *** ## Code Examples ```python theme={null} import os 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", } # Predefined period response = requests.get( f"{BASE_URL}/v1/usage/report", headers=headers, params={"period": "week"}, ) data = response.json() print(f"Period: {data['period']} ({data['start_date']} to {data['end_date']})") 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']}" ) # Custom date range response = requests.get( f"{BASE_URL}/v1/usage/report", headers=headers, params={"start_date": "2026-03-01", "end_date": "2026-03-31"}, ) ``` ```typescript theme={null} 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; } const res = await fetch( `${BASE_URL}/v1/usage/report?period=week`, { method: "GET", headers: { "x-api-key": API_KEY, "Content-Type": "application/json", }, } ); if (!res.ok) { throw new Error(`HTTP ${res.status}: ${await res.text()}`); } const data = (await res.json()) as UsageReportOutput; console.log(`Period: ${data.period} (${data.start_date} to ${data.end_date})`); 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}` ); } ``` ```rust theme={null} 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, period: String, start_date: String, end_date: String, timestamp: String, } fn main() -> Result<(), Box> { 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: {} ({} to {})", data.period, data.start_date, data.end_date, ); 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(()) } ``` ```go theme={null} 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 (%s to %s)\n", data.Period, data.StartDate, data.EndDate) 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, ) } } ``` ```bash theme={null} # Default period (month) 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" ``` *** ## Response Schema ### UsageReportOutput Object | Field | Type | Description | | ------------ | ---------------------- | ---------------------------------------------------------------- | | `results` | `List[UsageReportDay]` | Daily usage breakdown, sorted ascending by date | | `period` | `string` | The period that was applied: `day`, `week`, `month`, or `custom` | | `start_date` | `string` | Start date of the report (`YYYY-MM-DD`) | | `end_date` | `string` | End date of the report (`YYYY-MM-DD`) | | `timestamp` | `string` | ISO timestamp when the report was generated | ### UsageReportDay Object | Field | Type | Description | | --------------- | --------- | ------------------------------ | | `day` | `string` | Date in `YYYY-MM-DD` format | | `total_cost` | `number` | Total cost in USD for this day | | `input_tokens` | `integer` | Total input tokens consumed | | `output_tokens` | `integer` | Total output tokens consumed | | `request_count` | `integer` | Total number of API requests | ### Example Response ```json theme={null} { "results": [ { "day": "2026-03-28", "total_cost": 1.234567, "input_tokens": 42000, "output_tokens": 9800, "request_count": 15 }, { "day": "2026-03-29", "total_cost": 0.856234, "input_tokens": 28000, "output_tokens": 6200, "request_count": 8 } ], "period": "week", "start_date": "2026-03-23", "end_date": "2026-03-29", "timestamp": "2026-03-29T18:30:00+00:00" } ``` *** ## Error Responses | HTTP Status | Cause | | ----------- | ------------------------------------ | | 400 | `start_date` is after `end_date` | | 401 | Missing or invalid API key | | 429 | Rate limit exceeded | | 500 | Internal error generating the report | *** ## How Data is Aggregated The endpoint reads from API request logs and groups entries by calendar day (UTC). For each completion log, the response `usage` object contributes `input_tokens`, `output_tokens`, and `total_cost` to that day's totals. Every logged request increments the daily `request_count`. Days with zero activity are omitted from the results. *** ## Related * [Get Credit Balance](/docs/examples/examples/account-credits) — check your current credit balance * [Pricing Details](/docs/examples/examples/pricing-details-basic) — see per-operation costs * [Rate Limits](/docs/examples/api_examples/rate_limits) — check rate limit status