> ## Documentation Index
> Fetch the complete documentation index at: https://velt.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

**x-velt-api-key** `string` *required*

Your API key.

**x-velt-auth-token** `string` *required*

Your [Auth Token](https://velt.dev/docs/security/auth-tokens.md).

# Body

#### Params

**data** `object` *required*

**properties**

**agentId** `string`

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

**year** `string`

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

**month** `string`

Two-digit month `"01"`–`"12"` (regex `^(0[1-9]|1[0-2])$`).

**model** `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)

```JSON theme={null}
{
  "data": {}
}
```

#### 2. Single agent analytics

```JSON theme={null}
{
  "data": {
    "agentId": "abc123def456"
  }
}
```

#### 3. Filtered by year and month

```JSON theme={null}
{
  "data": {
    "agentId": "abc123def456",
    "year": "2026",
    "month": "03"
  }
}
```

#### 4. Filtered by model

```JSON theme={null}
{
  "data": {
    "model": "gemini/gemini-3.6-flash"
  }
}
```

# 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

```JSON theme={null}
{
  "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. |

> [!NOTE]
>
> 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

```JSON theme={null}
{
  "error": {
    "message": "ERROR_MESSAGE",
    "status": "INVALID_ARGUMENT"
  }
}
```

**Errors:** `INVALID_ARGUMENT` (invalid `year` or `month` format).

```js theme={null}
{
  "result": {
    "status": "success",
    "message": "Analytics fetched successfully",
    "data": {
      "analytics": {
        "tokenUsage": { "allTime": { "requestCount": 0, "promptTokens": 0, "completionTokens": 0, "thoughtsTokens": 0, "totalTokens": 0 } },
        "executionCounts": {}
      }
    }
  }
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.