# Analytics

Usage analytics and token consumption for your AVCodex agent.

---

The analytics endpoints provide aggregate data on how your agent is being used: session counts, message volume, consumer growth, and token consumption broken down by model. Useful for tracking adoption across a dealer program or measuring how often field techs are using the agent.

## Usage analytics

```
GET /api/v1/apps/{appId}/analytics/usage
```

Returns a usage summary with a timeseries breakdown.

### Query parameters

| Parameter        | Type     | Default            | Description                                  |
|------------------|----------|--------------------|----------------------------------------------|
| `started_after`  | ISO 8601 | none (all time)    | Start of the date range.                     |
| `started_before` | ISO 8601 | none (all time)    | End of the date range.                       |
| `group_by`       | string   | `day`              | Timeseries granularity: `day`, `week`, `month`. |

### Example

```bash
curl "https://app.avcodex.com/api/v1/apps/YOUR_APP_ID/analytics/usage?started_after=2025-06-01T00:00:00Z&group_by=day" \
  -H "Authorization: Bearer avcodex_YOUR_API_KEY"
```

### Response

```json
{
  "data": {
    "summary": {
      "total_sessions": 1247,
      "unique_consumers": 342,
      "total_messages": 8934
    },
    "timeseries": [
      {
        "period": "2025-06-01T00:00:00.000Z",
        "session_count": 45,
        "message_count": 312
      },
      {
        "period": "2025-06-02T00:00:00.000Z",
        "session_count": 52,
        "message_count": 387
      }
    ]
  }
}
```

### Response fields

**Summary**

| Field              | Type    | Description                                  |
|--------------------|---------|----------------------------------------------|
| `total_sessions`   | integer | Total sessions in the date range.            |
| `unique_consumers` | integer | Distinct consumers who started a session.    |
| `total_messages`   | integer | Total messages sent and received.            |

**Timeseries entries**

| Field           | Type     | Description                          |
|-----------------|----------|--------------------------------------|
| `period`        | ISO 8601 | Start of the time bucket.            |
| `session_count` | integer  | Sessions in this period.             |
| `message_count` | integer  | Messages in this period.             |

### Weekly grouping

```bash
curl "https://app.avcodex.com/api/v1/apps/YOUR_APP_ID/analytics/usage?group_by=week&started_after=2025-01-01T00:00:00Z" \
  -H "Authorization: Bearer avcodex_YOUR_API_KEY"
```

---

## Token usage

```
GET /api/v1/apps/{appId}/analytics/token-usage
```

Returns token consumption totals, broken down by model. Useful for tracking spend and understanding which models the agent relies on.

### Query parameters

| Parameter        | Type     | Default          | Description                  |
|------------------|----------|------------------|------------------------------|
| `started_after`  | ISO 8601 | none (all time)  | Start of the date range.     |
| `started_before` | ISO 8601 | none (all time)  | End of the date range.       |

### Example

```bash
curl "https://app.avcodex.com/api/v1/apps/YOUR_APP_ID/analytics/token-usage?started_after=2025-06-01T00:00:00Z" \
  -H "Authorization: Bearer avcodex_YOUR_API_KEY"
```

### Response

```json
{
  "data": {
    "total": {
      "input_tokens": 2450000,
      "output_tokens": 1230000,
      "total_tokens": 3680000,
      "request_count": 4521
    },
    "by_model": [
      {
        "model": "gpt-4.1",
        "input_tokens": 1200000,
        "output_tokens": 600000,
        "total_tokens": 1800000,
        "request_count": 2100
      },
      {
        "model": "claude-sonnet-4-20250514",
        "input_tokens": 1250000,
        "output_tokens": 630000,
        "total_tokens": 1880000,
        "request_count": 2421
      }
    ]
  }
}
```

### Response fields

**`total` object**

| Field           | Type    | Description                               |
|-----------------|---------|-------------------------------------------|
| `input_tokens`  | integer | Total prompt/input tokens consumed.       |
| `output_tokens` | integer | Total completion/output tokens consumed.  |
| `total_tokens`  | integer | Sum of input and output tokens.           |
| `request_count` | integer | Total number of LLM requests.             |

**Per-model breakdown (`by_model` entries)**

| Field           | Type    | Description                          |
|-----------------|---------|--------------------------------------|
| `model`         | string  | Model identifier.                    |
| `input_tokens`  | integer | Input tokens for this model.         |
| `output_tokens` | integer | Output tokens for this model.        |
| `total_tokens`  | integer | Total tokens for this model.         |
| `request_count` | integer | Number of LLM requests for this model.|

*AVCodex · Your AV expertise. Amplified by AI.*