> ## Documentation Index
> Fetch the complete documentation index at: https://velt-raghul-agent-docs.mintlify.site/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. 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

<ParamField header="x-velt-api-key" type="string" required>
  Your API key.
</ParamField>

<ParamField header="x-velt-auth-token" type="string" required>
  Your [Auth Token](/security/auth-tokens).
</ParamField>

# Body

#### Params

<ParamField body="data" type="object" required>
  <Expandable title="properties">
    <ParamField body="agentId" type="string">
      Min 1 char. Agent ID. Omit for aggregate analytics across all agents.
    </ParamField>

    <ParamField body="year" type="string">
      4-digit year string (e.g. `"2026"`). Regex `^\d{4}$`.
    </ParamField>

    <ParamField body="month" type="string">
      Two-digit month string (e.g. `"01"` to `"12"`). Regex `^(0[1-9]|1[0-2])$`.
    </ParamField>

    <ParamField body="model" type="string">
      Filter by model identifier (e.g. `"gemini-3-flash-preview"`).
    </ParamField>
  </Expandable>
</ParamField>

## **Example Requests**

#### 1. Aggregate analytics for the workspace

```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-3-flash-preview"
  }
}
```

# Response

#### 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-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

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

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

<ResponseExample>
  ```js theme={null}
  {
    "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": {}
        }
      }
    }
  }
  ```
</ResponseExample>