# Analytics

Usage analytics and token consumption for your Chipp app

---

The analytics endpoints provide aggregate data about how your app is being used -- session counts, message volume, consumer growth, and token consumption broken down by model.

## Usage Analytics

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

Returns a summary of app usage along 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`, or `month` |

### Example

```bash
curl "https://build.chipp.ai/api/v1/apps/YOUR_APP_ID/analytics/usage?started_after=2025-06-01T00:00:00Z&group_by=day" \
  -H "Authorization: Bearer chipp_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://build.chipp.ai/api/v1/apps/YOUR_APP_ID/analytics/usage?group_by=week&started_after=2025-01-01T00:00:00Z" \
  -H "Authorization: Bearer chipp_YOUR_API_KEY"
```

---

## Token Usage

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

Returns token consumption totals, broken down by model. Useful for monitoring costs and understanding which models your app 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://build.chipp.ai/api/v1/apps/YOUR_APP_ID/analytics/token-usage?started_after=2025-06-01T00:00:00Z" \
  -H "Authorization: Bearer chipp_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 |