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
string
required
Your API key.
string
required
Your Auth Token.
Body
Params
object
required
Show properties
Show properties
string
Min 1 char. Agent ID. Omit for aggregate analytics across all agents.
string
4-digit year string (regex
^\d{4}$), e.g. "2026".string
Two-digit month
"01"–"12" (regex ^(0[1-9]|1[0-2])$).string
Filter by model. Use the full provider-prefixed model id (e.g.
"gemini/gemini-3.6-flash"). This narrows byModel only; allTime, yearly, and monthly are unaffected. A value that matches no stored key returns byModel: {}.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?
⌘I

