Skip to main content
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>'
{
  "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": "Llama 3.3 70B",
      "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,
      "Llama 3.3 70B": 5.5,
      "Claude 3.5 Sonnet": 3.2
    }
  ],
  "topModels": [
    "Llama 3.3 70B",
    "Claude 3.5 Sonnet"
  ],
  "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"
  ]
}
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., “Llama 3.3 70B”)
  • 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

​
byModel
object[]
required

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

​
byModelDaily
object[]
required

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

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

​
byKeyDaily
object[]
required

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

​
topKeyNames
string[]
required

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