Get Agent Analytics
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>"
}
}
'import requests
url = "https://api.velt.dev/v2/agents/analytics/get"
payload = { "data": {
"agentId": "<string>",
"year": "<string>",
"month": "<string>",
"model": "<string>"
} }
headers = {
"x-velt-api-key": "<x-velt-api-key>",
"x-velt-auth-token": "<x-velt-auth-token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {
'x-velt-api-key': '<x-velt-api-key>',
'x-velt-auth-token': '<x-velt-auth-token>',
'Content-Type': 'application/json'
},
body: JSON.stringify({
data: {agentId: '<string>', year: '<string>', month: '<string>', model: '<string>'}
})
};
fetch('https://api.velt.dev/v2/agents/analytics/get', 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.velt.dev/v2/agents/analytics/get",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'data' => [
'agentId' => '<string>',
'year' => '<string>',
'month' => '<string>',
'model' => '<string>'
]
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"x-velt-api-key: <x-velt-api-key>",
"x-velt-auth-token: <x-velt-auth-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"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.velt.dev/v2/agents/analytics/get"
payload := strings.NewReader("{\n \"data\": {\n \"agentId\": \"<string>\",\n \"year\": \"<string>\",\n \"month\": \"<string>\",\n \"model\": \"<string>\"\n }\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("x-velt-api-key", "<x-velt-api-key>")
req.Header.Add("x-velt-auth-token", "<x-velt-auth-token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.velt.dev/v2/agents/analytics/get")
.header("x-velt-api-key", "<x-velt-api-key>")
.header("x-velt-auth-token", "<x-velt-auth-token>")
.header("Content-Type", "application/json")
.body("{\n \"data\": {\n \"agentId\": \"<string>\",\n \"year\": \"<string>\",\n \"month\": \"<string>\",\n \"model\": \"<string>\"\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.velt.dev/v2/agents/analytics/get")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["x-velt-api-key"] = '<x-velt-api-key>'
request["x-velt-auth-token"] = '<x-velt-auth-token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"data\": {\n \"agentId\": \"<string>\",\n \"year\": \"<string>\",\n \"month\": \"<string>\",\n \"model\": \"<string>\"\n }\n}"
response = http.request(request)
puts response.read_body{
"result": {
"status": "success",
"message": "Analytics fetched successfully",
"data": {
"analytics": {
"tokenUsage": { "allTime": { "requestCount": 0, "promptTokens": 0, "completionTokens": 0, "thoughtsTokens": 0, "totalTokens": 0 } },
"executionCounts": {}
}
}
}
}
Analytics
Get Agent Analytics
POST
/
v2
/
agents
/
analytics
/
get
Get Agent Analytics
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>"
}
}
'import requests
url = "https://api.velt.dev/v2/agents/analytics/get"
payload = { "data": {
"agentId": "<string>",
"year": "<string>",
"month": "<string>",
"model": "<string>"
} }
headers = {
"x-velt-api-key": "<x-velt-api-key>",
"x-velt-auth-token": "<x-velt-auth-token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {
'x-velt-api-key': '<x-velt-api-key>',
'x-velt-auth-token': '<x-velt-auth-token>',
'Content-Type': 'application/json'
},
body: JSON.stringify({
data: {agentId: '<string>', year: '<string>', month: '<string>', model: '<string>'}
})
};
fetch('https://api.velt.dev/v2/agents/analytics/get', 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.velt.dev/v2/agents/analytics/get",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'data' => [
'agentId' => '<string>',
'year' => '<string>',
'month' => '<string>',
'model' => '<string>'
]
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"x-velt-api-key: <x-velt-api-key>",
"x-velt-auth-token: <x-velt-auth-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"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.velt.dev/v2/agents/analytics/get"
payload := strings.NewReader("{\n \"data\": {\n \"agentId\": \"<string>\",\n \"year\": \"<string>\",\n \"month\": \"<string>\",\n \"model\": \"<string>\"\n }\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("x-velt-api-key", "<x-velt-api-key>")
req.Header.Add("x-velt-auth-token", "<x-velt-auth-token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.velt.dev/v2/agents/analytics/get")
.header("x-velt-api-key", "<x-velt-api-key>")
.header("x-velt-auth-token", "<x-velt-auth-token>")
.header("Content-Type", "application/json")
.body("{\n \"data\": {\n \"agentId\": \"<string>\",\n \"year\": \"<string>\",\n \"month\": \"<string>\",\n \"model\": \"<string>\"\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.velt.dev/v2/agents/analytics/get")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["x-velt-api-key"] = '<x-velt-api-key>'
request["x-velt-auth-token"] = '<x-velt-auth-token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"data\": {\n \"agentId\": \"<string>\",\n \"year\": \"<string>\",\n \"month\": \"<string>\",\n \"model\": \"<string>\"\n }\n}"
response = http.request(request)
puts response.read_body{
"result": {
"status": "success",
"message": "Analytics fetched successfully",
"data": {
"analytics": {
"tokenUsage": { "allTime": { "requestCount": 0, "promptTokens": 0, "completionTokens": 0, "thoughtsTokens": 0, "totalTokens": 0 } },
"executionCounts": {}
}
}
}
}
Use this API to fetch AI token usage analytics and execution counts. Data is aggregated from per-workspace Firestore usage documents. Filter by
Errors:
agentId, year, month, and/or model.
Endpoint
POST https://api.velt.dev/v2/agents/analytics/get
Headers
Your Auth Token.
Body
Params
Show properties
Show properties
Example Requests
1. Aggregate analytics (all agents)
{
"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/gemini-3.6-flash"
}
}
Response
Theanalytics object maps to the AgentAnalyticsResponse interface. Model keys are formatted as provider_model (e.g. "claude_claude-sonnet-5"). Dots and slashes in the provider or model id are replaced with underscores, so gemini/gemini-3.6-flash is keyed as "gemini_gemini-3_6-flash".
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-5": { "requestCount": 350, "promptTokens": 700000, "completionTokens": 210000, "thoughtsTokens": 20000, "totalTokens": 930000 },
"gemini_gemini-3_6-flash": { "requestCount": 500, "promptTokens": 1000000, "completionTokens": 300000, "thoughtsTokens": 10000, "totalTokens": 1310000 }
}
},
"monthly": {
"03": {
"claude_claude-sonnet-5": { "requestCount": 120, "promptTokens": 240000, "completionTokens": 72000, "thoughtsTokens": 5000, "totalTokens": 317000 }
}
},
"byModel": {
"claude_claude-sonnet-5": { "requestCount": 500, "promptTokens": 1000000, "completionTokens": 300000, "thoughtsTokens": 50000, "totalTokens": 1350000 },
"gemini_gemini-3_6-flash": { "requestCount": 750, "promptTokens": 1500000, "completionTokens": 450000, "thoughtsTokens": 0, "totalTokens": 1950000 }
}
},
"executionCounts": {
"abc123def456": { "executionCount": 45, "lastExecutedAt": 1711900000000 },
"spell-check": { "executionCount": 142, "lastExecutedAt": 1711900000000 }
}
}
}
}
}
TokenUsageSummary fields (repeated in every breakdown):
| Field | Type | Description |
|---|---|---|
requestCount | number | Total number of 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 | Present When | Description |
|---|---|---|---|
allTime | TokenUsageSummary | always | Aggregate across all time. |
yearly | Record<year, Record<model, TokenUsageSummary>> | yearly usage recorded | Keyed by year string, then by model key. |
monthly | Record<month, Record<model, TokenUsageSummary>> | request includes year | Keyed by month ("01" to "12"), then by model key. |
byModel | Record<model, TokenUsageSummary> | usage recorded | Cross-year aggregate keyed by model. |
Only
tokenUsage.allTime and executionCounts are guaranteed. Read the rest defensively rather than assuming the keys exist.monthly is returned only when the request includes a year. It is the per-month breakdown of that year, and month narrows it further. Without year, the monthly key is absent no matter how much monthly usage exists, so month on its own has no effect.yearly and byModel are omitted when the workspace has no recorded usage to report for them.executionCounts map:
Keyed by agentId. When you pass an agentId filter, the map is narrowed to that single agent, or returned as {} when that agent has no recorded executions.
| 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"
}
}
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 } },
"executionCounts": {}
}
}
}
}
Was this page helpful?

