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

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

200

{
  "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"
  ]
}

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

200

application/json

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)