Get Agent Analytics

POST /v2/agents/analytics/get

Get Agent Analytics

cURL

curl --request POST \
  --url https://api.velt.dev/v2/agents/analytics/get \
  --header 'Content-Type: application/json' \
  --header 'x-velt-api-key: <x-velt-api-key>' \
  --header 'x-velt-auth-token: <x-velt-auth-token>' \
  --data '
{
  "data": {
    "agentId": "<string>",
    "year": "<string>",
    "month": "<string>",
    "model": "<string>"
  }
}
'

{
  "result": {
    "status": "success",
    "message": "Analytics fetched successfully",
    "data": {
      "analytics": {
        "tokenUsage": {
          "allTime": { "requestCount": 0, "promptTokens": 0, "completionTokens": 0, "thoughtsTokens": 0, "totalTokens": 0 },
          "yearly": {},
          "monthly": {},
          "byModel": {}
        },
        "executionCounts": {}
      }
    }
  }
}

Use this API to fetch AI token usage analytics and execution counts. Token usage is tracked per workspace, per agent, per model, and per request, with breakdowns by allTime, yearly, monthly, and byModel.

Filters narrow what is returned but do not change the response shape — empty buckets simply contain zeros.

Endpoint

POST https://api.velt.dev/v2/agents/analytics/get

Headers

x-velt-api-key · string · required

Your API key.

x-velt-auth-token · string · required

Your Auth Token.

Body

Params

data · object · required

Show properties

agentId · string

Min 1 char. Agent ID. Omit for aggregate analytics across all agents.

year · string

4-digit year string (e.g. "2026"). Regex ^\d{4}$.

month · string

Two-digit month string (e.g. "01" to "12"). Regex ^(0[1-9]|1[0-2])$.

model · string

Filter by model identifier (e.g. "gemini-3-flash-preview").

Example Requests

1. Aggregate analytics for the workspace

{
  "data": {}
}

2. Single agent analytics

{
  "data": {
    "agentId": "abc123def456"
  }
}

3. Filtered by year and month

{
  "data": {
    "agentId": "abc123def456",
    "year": "2026",
    "month": "03"
  }
}

4. Filtered by model

{
  "data": {
    "model": "gemini-3-flash-preview"
  }
}

Response

Success Response

{
  "result": {
    "status": "success",
    "message": "Analytics fetched successfully",
    "data": {
      "analytics": {
        "tokenUsage": {
          "allTime": {
            "requestCount": 1250,
            "promptTokens": 2500000,
            "completionTokens": 750000,
            "thoughtsTokens": 50000,
            "totalTokens": 3300000
          },
          "yearly": {
            "2026": {
              "claude_claude-sonnet-4-6": {
                "requestCount": 350,
                "promptTokens": 700000,
                "completionTokens": 210000,
                "thoughtsTokens": 20000,
                "totalTokens": 930000
              },
              "gemini_gemini-3-flash-preview": {
                "requestCount": 500,
                "promptTokens": 1000000,
                "completionTokens": 300000,
                "thoughtsTokens": 10000,
                "totalTokens": 1310000
              }
            }
          },
          "monthly": {
            "03": {
              "claude_claude-sonnet-4-6": {
                "requestCount": 120,
                "promptTokens": 240000,
                "completionTokens": 72000,
                "thoughtsTokens": 5000,
                "totalTokens": 317000
              }
            }
          },
          "byModel": {
            "claude_claude-sonnet-4-6": {
              "requestCount": 500,
              "promptTokens": 1000000,
              "completionTokens": 300000,
              "thoughtsTokens": 50000,
              "totalTokens": 1350000
            },
            "gemini_gemini-3-flash-preview": {
              "requestCount": 750,
              "promptTokens": 1500000,
              "completionTokens": 450000,
              "thoughtsTokens": 0,
              "totalTokens": 1950000
            }
          }
        },
        "executionCounts": {
          "abc123def456": { "executionCount": 45, "lastExecutedAt": 1711900000000 },
          "spell-check": { "executionCount": 142, "lastExecutedAt": 1711900000000 },
          "broken-links": { "executionCount": 210, "lastExecutedAt": 1711800000000 }
        }
      }
    }
  }
}

TokenUsageSummary fields (repeated in every breakdown)

Field	Type	Description
requestCount	number	Total LLM API requests
promptTokens	number	Total input tokens consumed
completionTokens	number	Total output tokens generated
thoughtsTokens	number	Thinking/reasoning tokens (model-dependent; 0 for Gemini)
totalTokens	number	Total tokens consumed

tokenUsage breakdown keys

Key	Type	Description
allTime	TokenUsageSummary	Aggregate across all time
yearly	Record<year, Record<modelKey, Summary>>	Keyed by 4-digit year, then by sanitised model key
monthly	Record<month, Record<modelKey, Summary>>	Keyed by "01"-"12", then by sanitised model key
byModel	Record<modelKey, Summary>	Cross-year aggregate, keyed by sanitised model (e.g. "claude_claude-sonnet-4-6")

executionCounts map

Field	Type	Description
executionCount	number	Total executions for this agent
lastExecutedAt	number | null	Epoch ms of last execution. null if never.

Failure Response

{
  "error": {
    "message": "ERROR_MESSAGE",
    "status": "INVALID_ARGUMENT"
  }
}

Errors: INVALID_ARGUMENT (invalid year or month format).

{
  "result": {
    "status": "success",
    "message": "Analytics fetched successfully",
    "data": {
      "analytics": {
        "tokenUsage": {
          "allTime": { "requestCount": 0, "promptTokens": 0, "completionTokens": 0, "thoughtsTokens": 0, "totalTokens": 0 },
          "yearly": {},
          "monthly": {},
          "byModel": {}
        },
        "executionCounts": {}
      }
    }
  }
}