Billing
Billing Usage Analytics (Beta)
Beta: This endpoint is currently in beta and may be unstable. Request/response schemas and behavior may change without notice.
Get aggregated usage analytics for the authenticated user with breakdowns by date, model, and API key. This endpoint provides summary views of your API usage, ideal for dashboards and usage monitoring. Data is cached for 10 minutes.
GET
/
billing
/
usage-analytics
/api/v1/billing/usage-analytics
curl --request GET \
--url https://api.venice.ai/api/v1/billing/usage-analytics \
--header 'Authorization: Bearer <token>'import requests
url = "https://api.venice.ai/api/v1/billing/usage-analytics"
headers = {"Authorization": "Bearer <token>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
fetch('https://api.venice.ai/api/v1/billing/usage-analytics', 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.venice.ai/api/v1/billing/usage-analytics",
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.venice.ai/api/v1/billing/usage-analytics"
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.venice.ai/api/v1/billing/usage-analytics")
.header("Authorization", "Bearer <token>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.venice.ai/api/v1/billing/usage-analytics")
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_body{
"lookback": "7d",
"byDate": [
{
"date": "2024-01-15T00:00:00.000Z",
"USD": 0.5,
"DIEM": 10.25
},
{
"date": "2024-01-14T00:00:00.000Z",
"USD": 0.3,
"DIEM": 8.75
}
],
"byModel": [
{
"modelName": "GLM 5.1",
"unitType": "tokens",
"modelType": "LLM",
"totalUsd": 0.4,
"totalDiem": 12.5,
"totalUnits": 50000,
"breakdown": [
{
"type": "Output",
"usd": 0.3,
"diem": 10,
"units": 35000
},
{
"type": "Input",
"usd": 0.1,
"diem": 2.5,
"units": 15000
}
]
}
],
"byModelDaily": [
{
"date": 1705276800000,
"GLM 5.1": 5.5,
"Kimi K2.6": 3.2
}
],
"topModels": [
"GLM 5.1",
"Kimi K2.6"
],
"byKey": [
{
"apiKeyId": "key_abc123",
"description": "Production Key",
"totalUsd": 0.8,
"totalDiem": 15,
"totalUnits": 75000
},
{
"apiKeyId": null,
"description": "Web App",
"totalUsd": 0,
"totalDiem": 4,
"totalUnits": 25000
}
],
"byKeyDaily": [
{
"date": 1705276800000,
"Production Key": 8.5,
"Web App": 2
}
],
"topKeyNames": [
"Production Key",
"Web App"
]
}{
"error": "<string>",
"details": {
"_errors": [],
"field": {
"_errors": [
"Field is required"
]
}
}
}{
"error": "<string>"
}{
"error": "This API key is restricted to configured IP addresses, and this request's source IP is not allowed"
}{
"error": "<string>"
}{
"error": "<string>"
}This is a beta endpoint and may be unstable or change without notice.
Query Parameters
You can specify the time period for analytics using either:- lookback: A relative period like “7d” (7 days), “30d” (30 days), up to “90d” (90 days)
- startDate and endDate: A custom date range in
YYYY-MM-DDformat. Send both to use a custom range.
If you send only one of
startDate or endDate, the request does not fail: it returns 200 using the default 7-day lookback and ignores the date, with no warning. Always send both together.A lookback longer than 90 days is capped at 90d. A startDate/endDate range longer than 90 days returns 400.Response Fields
lookback
The lookback period used for the query. Either in “Nd” format (e.g., “7d”) or “startDate:endDate” format.byDate
Daily usage totals for the requested period.- date: The date in
YYYY-MM-DDformat - USD: Total usage in USD for that day
- DIEM: Total usage in DIEM for that day
byModel
Usage breakdown by model, sorted by total spend (highest first).- modelName: Display name of the model (e.g., “GLM 5”)
- unitType: Type of units consumed (tokens, images, chars, minutes, seconds)
- modelType: Type of model (LLM, IMAGE, TTS, ASR, VIDEO), or null
- totalUsd: Total USD spent on this model
- totalDiem: Total DIEM spent on this model
- totalUnits: Total units consumed for this model
- breakdown: Array of usage breakdowns by type (only present if multiple types). Each entry contains:
- type: Token type (e.g., “Input”, “Output”, “Cache Read”, “Cache Write”)
- usd: USD amount for this breakdown
- diem: DIEM amount for this breakdown
- units: Number of units for this breakdown
byModelDaily
Daily chart data for top 8 models. Each entry contains a “date” (timestamp) plus model names as keys with DIEM usage values.topModels
Array of the top 8 model names by usage, for chart legends.byKey
Usage breakdown by API key, sorted by total spend (highest first).- apiKeyId: The API key ID, or null if usage was from the web app
- description: API key description or “Web App”
- totalUsd: Total USD spent via this key
- totalDiem: Total DIEM spent via this key
- totalUnits: Total units consumed via this key
byKeyDaily
Daily chart data for top 8 API keys. Each entry contains a “date” (timestamp) plus key descriptions as keys with DIEM usage values.topKeyNames
Array of the top 8 API key descriptions by usage, for chart legends.Example Usage
# Get usage analytics for the past 7 days (default)
curl -X GET "https://api.venice.ai/api/v1/billing/usage-analytics" \
-H "Authorization: Bearer YOUR_API_KEY"
# Get usage analytics for the past 30 days
curl -X GET "https://api.venice.ai/api/v1/billing/usage-analytics?lookback=30d" \
-H "Authorization: Bearer YOUR_API_KEY"
# Get usage analytics for a specific date range
curl -X GET "https://api.venice.ai/api/v1/billing/usage-analytics?startDate=2024-01-01&endDate=2024-01-31" \
-H "Authorization: Bearer YOUR_API_KEY"
Authorizations
Query Parameters
Response
Successful response with aggregated usage analytics
Aggregated usage analytics response with breakdowns by date, model, and API key
Was this page helpful?
⌘I
/api/v1/billing/usage-analytics
curl --request GET \
--url https://api.venice.ai/api/v1/billing/usage-analytics \
--header 'Authorization: Bearer <token>'import requests
url = "https://api.venice.ai/api/v1/billing/usage-analytics"
headers = {"Authorization": "Bearer <token>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
fetch('https://api.venice.ai/api/v1/billing/usage-analytics', 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.venice.ai/api/v1/billing/usage-analytics",
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.venice.ai/api/v1/billing/usage-analytics"
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.venice.ai/api/v1/billing/usage-analytics")
.header("Authorization", "Bearer <token>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.venice.ai/api/v1/billing/usage-analytics")
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_body{
"lookback": "7d",
"byDate": [
{
"date": "2024-01-15T00:00:00.000Z",
"USD": 0.5,
"DIEM": 10.25
},
{
"date": "2024-01-14T00:00:00.000Z",
"USD": 0.3,
"DIEM": 8.75
}
],
"byModel": [
{
"modelName": "GLM 5.1",
"unitType": "tokens",
"modelType": "LLM",
"totalUsd": 0.4,
"totalDiem": 12.5,
"totalUnits": 50000,
"breakdown": [
{
"type": "Output",
"usd": 0.3,
"diem": 10,
"units": 35000
},
{
"type": "Input",
"usd": 0.1,
"diem": 2.5,
"units": 15000
}
]
}
],
"byModelDaily": [
{
"date": 1705276800000,
"GLM 5.1": 5.5,
"Kimi K2.6": 3.2
}
],
"topModels": [
"GLM 5.1",
"Kimi K2.6"
],
"byKey": [
{
"apiKeyId": "key_abc123",
"description": "Production Key",
"totalUsd": 0.8,
"totalDiem": 15,
"totalUnits": 75000
},
{
"apiKeyId": null,
"description": "Web App",
"totalUsd": 0,
"totalDiem": 4,
"totalUnits": 25000
}
],
"byKeyDaily": [
{
"date": 1705276800000,
"Production Key": 8.5,
"Web App": 2
}
],
"topKeyNames": [
"Production Key",
"Web App"
]
}{
"error": "<string>",
"details": {
"_errors": [],
"field": {
"_errors": [
"Field is required"
]
}
}
}{
"error": "<string>"
}{
"error": "This API key is restricted to configured IP addresses, and this request's source IP is not allowed"
}{
"error": "<string>"
}{
"error": "<string>"
}