Skip to main content
POST
Get Agent Analytics
Use this API to fetch AI token usage analytics and execution counts. Data is aggregated from per-workspace Firestore usage documents. Filter by agentId, year, month, and/or model.

Endpoint

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

Headers

string
required
Your API key.
string
required

Body

Params

object
required

Example Requests

1. Aggregate analytics (all agents)

2. Single agent analytics

3. Filtered by year and month

4. Filtered by model

Response

The analytics 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

TokenUsageSummary fields (repeated in every breakdown): tokenUsage breakdown keys:
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.

Failure Response

Errors: INVALID_ARGUMENT (invalid year or month format).