Billing Usage Analytics | Venice API Docs

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>'

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))

}

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": "<string>"
}

{
  "error": "<string>"
}

This is a beta endpoint and may be unstable or 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 data for building dashboards and monitoring consumption. Data is cached for 10 minutes.

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-DD format. Both are required if either is provided.

If no parameters are specified, the default lookback period is 7 days.

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-DD format
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

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Query Parameters

lookback

string

default:7d

Lookback period for usage data. Format: number followed by "d" (e.g., "7d", "30d"). Maximum: 90d

Pattern: ^[1-9]\d*d$

Example:

"7d"

startDate

string

Start date for filtering records (YYYY-MM-DD). If provided, endDate is also required.

Pattern: ^\d{4}-\d{2}-\d{2}$

Example:

"2024-01-01T00:00:00.000Z"

endDate

string

End date for filtering records (YYYY-MM-DD). If provided, startDate is also required.

Pattern: ^\d{4}-\d{2}-\d{2}$

Example:

"2024-01-31T00:00:00.000Z"

Response

Successful response with aggregated usage analytics

Aggregated usage analytics response with breakdowns by date, model, and API key

lookback

string

required

The lookback period used for the query. Either "Nd" format or "startDate:endDate" format.

Example:

"7d"

byDate

object[]

required

Daily usage totals for the requested period

Show child attributes

byModel

object[]

required

Usage breakdown by model, sorted by total spend (highest first)

Show child attributes

byModelDaily

object[]

required

Daily chart data for top 8 models. Each entry has "date" (timestamp) plus model names as keys.

Show child attributes

topModels

string[]

required

Names of the top 8 models by usage (for chart legends)

byKey

object[]

required

Usage breakdown by API key, sorted by total spend (highest first)

Show child attributes

byKeyDaily

object[]

required

Daily chart data for top 8 API keys. Each entry has "date" (timestamp) plus key descriptions as keys.

Show child attributes

topKeyNames

string[]

required

Descriptions of the top 8 API keys by usage (for chart legends)

⌘I

/api/v1/billing/usage-analytics

curl --request GET \
  --url https://api.venice.ai/api/v1/billing/usage-analytics \
  --header 'Authorization: Bearer <token>'

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))

}

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": "<string>"
}

{
  "error": "<string>"
}

Venice APIs

Billing Usage Analytics (Beta)

Query Parameters

Response Fields

lookback

byDate

byModel

byModelDaily

topModels

byKey

byKeyDaily

topKeyNames

Example Usage

Authorizations

Query Parameters

Response

​Query Parameters

​Response Fields

​lookback

​byDate

​byModel

​byModelDaily

​topModels

​byKey

​byKeyDaily

​topKeyNames

​Example Usage

Authorizations

Query Parameters

Response

Query Parameters

Response Fields

lookback

byDate

byModel

byModelDaily

topModels

byKey

byKeyDaily

topKeyNames

Example Usage