# Analytics API Reference

Query aggregated analytics data for your operator — KPIs, revenue trends, player lists, game performance, and payment provider statistics.

**Base path:** `/functions/v1/analytics-api`

**Authentication:** `Authorization: Bearer oh_live_...` or Supabase JWT

## Rate limits

| Action | Limit |
|---|---|
| Read queries | 200 / minute |
| Export queries | 5 / minute |
| View refresh | 1 / minute |

## Common parameters

### Range filtering

Most endpoints accept a `range` query parameter:

| Value | Description |
|---|---|
| `7d` | Last 7 days |
| `14d` | Last 14 days |
| `30d` | Last 30 days |
| `90d` | Last 90 days |
| `2026-01-01:2026-03-31` | Custom date range (ISO format) |

## Response size limit

All responses are capped at **1 MB**. If the data exceeds this limit, it is truncated and the response includes `"truncated": true`.

---

## KPIs {#kpis}

```
GET /analytics-api/analytics/kpis
```

Returns aggregate KPIs for your operator.

### Query parameters

| Parameter | Type | Description |
|---|---|---|
| `range` | string | Date range filter (see above) |

### Example

```bash
curl "https://api.onehazel.com/analytics-api/analytics/kpis?range=30d" \
  -H "Authorization: Bearer oh_live_YOUR_API_KEY"
```

### Response

```json
{
  "success": true,
  "data": {
    "kpis": {
      "total_players": 1250,
      "active_players_today": 342,
      "total_ggr": 45230.50,
      "total_deposits": 128500.00,
      "total_withdrawals": 83269.50,
      "avg_deposit": 102.80
    },
    "refreshed_at": "2026-04-06T06:00:00.000Z"
  }
}
```

- `active_players_today` is based on players with activity in the last 7 days (not strictly today)
- `avg_deposit` is total deposits divided by the number of depositing players
- `refreshed_at` indicates when the materialized views were last refreshed (null if using raw table fallback)

---

## Revenue {#revenue}

```
GET /analytics-api/analytics/revenue
```

Returns revenue time series data.

### Query parameters

| Parameter | Type | Default | Description |
|---|---|---|---|
| `period` | string | `daily` | Aggregation period: `daily`, `weekly`, or `monthly` |
| `range` | string | — | Date range filter |

Default lookback: 30 days for daily, 12 weeks for weekly, 12 months for monthly.

### Example

```bash
curl "https://api.onehazel.com/analytics-api/analytics/revenue?period=daily&range=7d" \
  -H "Authorization: Bearer oh_live_YOUR_API_KEY"
```

### Response

```json
{
  "success": true,
  "data": {
    "period": "daily",
    "rows": [
      {
        "date": "2026-03-31",
        "total_ggr": 1520.50,
        "total_deposits": 4200.00,
        "depositing_players": 42,
        "active_players": 185
      },
      {
        "date": "2026-04-01",
        "total_ggr": 1680.25,
        "total_deposits": 3850.00,
        "depositing_players": 38,
        "active_players": 192
      }
    ]
  },
  "truncated": false
}
```

---

## Players {#players}

```
GET /analytics-api/analytics/players
```

Returns a paginated list of entities.

::: warning Required parameter
The `entity_type` query parameter is **required**. Requests without it return HTTP `400`.
:::

### Query parameters

| Parameter | Type | Default | Description |
|---|---|---|---|
| `entity_type` | string | — | **Required.** Entity type to query (e.g. `player`) |
| `search` | string | — | Filter by external ID (partial match) |
| `sort` | string | `created_at` | Sort column: `created_at`, `updated_at`, or `external_id` |
| `direction` | string | `desc` | Sort direction: `asc` or `desc` |
| `limit` | integer | 50 | Results per page (max 100) |
| `offset` | integer | 0 | Pagination offset |

### Example

```bash
curl "https://api.onehazel.com/analytics-api/analytics/players?entity_type=player&limit=10&search=james" \
  -H "Authorization: Bearer oh_live_YOUR_API_KEY"
```

### Response

```json
{
  "success": true,
  "data": {
    "players": [
      {
        "id": "ent_a1b2c3d4e5f67890",
        "external_id": "player_12345",
        "entity_type": "player",
        "data": { "country": "GB", "currency": "GBP", "status": "active" },
        "created_at": "2026-04-01T10:00:00.000Z",
        "updated_at": "2026-04-06T14:30:00.000Z"
      }
    ],
    "total": 1,
    "has_more": false
  }
}
```

::: info PII in list responses
PII fields remain encrypted in list responses. Only the [player detail](#player-detail) endpoint decrypts PII.
:::

---

## Player detail {#player-detail}

```
GET /analytics-api/analytics/players/:id
```

Returns detailed information about a single entity, including decrypted PII, current states, and the 20 most recent events.

### Example

```bash
curl https://api.onehazel.com/analytics-api/analytics/players/player_12345 \
  -H "Authorization: Bearer oh_live_YOUR_API_KEY"
```

### Response

```json
{
  "success": true,
  "data": {
    "id": "ent_a1b2c3d4e5f67890",
    "external_id": "player_12345",
    "entity_type": "player",
    "data": {
      "first_name": "James",
      "last_name": "Wilson",
      "email": "james@example.com",
      "country": "GB",
      "currency": "GBP",
      "status": "active"
    },
    "states": [
      { "state_key": "balance", "value": { "amount": 145.50, "currency": "GBP" }, "updated_at": "2026-04-06T14:30:00Z" },
      { "state_key": "kyc_status", "value": "verified", "updated_at": "2026-04-05T09:00:00Z" }
    ],
    "recentEvents": [
      {
        "id": "eev_b2c3d4e5f6789012",
        "event_type": "transaction",
        "data": { "type": "deposit", "amount": 50.00, "currency": "GBP" },
        "created_at": "2026-04-06T14:00:00Z"
      }
    ],
    "created_at": "2026-04-01T10:00:00Z",
    "updated_at": "2026-04-06T14:30:00Z"
  }
}
```

---

## Games {#games}

```
GET /analytics-api/analytics/games
```

Returns game performance statistics.

### Query parameters

| Parameter | Type | Default | Description |
|---|---|---|---|
| `limit` | integer | 50 | Results per page (max 100) |
| `offset` | integer | 0 | Pagination offset |
| `range` | string | — | Date range filter (raw table path only) |

### Example

```bash
curl "https://api.onehazel.com/analytics-api/analytics/games?limit=10" \
  -H "Authorization: Bearer oh_live_YOUR_API_KEY"
```

### Response

```json
{
  "success": true,
  "data": {
    "games": [
      {
        "game_name": "European Roulette",
        "rounds": 15420,
        "ggr": 8250.75,
        "unique_players": 342,
        "avg_bet": 5.25
      },
      {
        "game_name": "Blackjack Classic",
        "rounds": 12180,
        "ggr": 6430.20,
        "unique_players": 287,
        "avg_bet": 10.50
      }
    ]
  },
  "truncated": false
}
```

---

## Providers {#providers}

```
GET /analytics-api/analytics/providers
```

Returns payment provider statistics — transaction volume, total amount, and success rate.

### Example

```bash
curl https://api.onehazel.com/analytics-api/analytics/providers \
  -H "Authorization: Bearer oh_live_YOUR_API_KEY"
```

### Response

```json
{
  "success": true,
  "data": {
    "providers": [
      {
        "provider": "stripe",
        "volume": 2450,
        "total_amount": 125000.00,
        "success_rate": 0.97
      },
      {
        "provider": "trustly",
        "volume": 890,
        "total_amount": 45000.00,
        "success_rate": 0.99
      }
    ]
  }
}
```

---

## Refresh {#refresh}

```
POST /analytics-api/analytics/refresh
```

Manually refreshes materialized views. Rate limited to 1 request per minute.

### Example

```bash
curl -X POST https://api.onehazel.com/analytics-api/analytics/refresh \
  -H "Authorization: Bearer oh_live_YOUR_API_KEY"
```

### Response

```json
{
  "success": true,
  "message": "Views refreshed",
  "refreshed_at": "2026-04-06T14:35:00.000Z"
}
```

---

## Error codes

| HTTP Status | Error Code | Description |
|---|---|---|
| `400` | `MISSING_FILTER` | `entity_type` is required for `/analytics/players` |
| `400` | `INVALID_PARAM` | Invalid parameter value (e.g. unknown period) |
| `401` | `UNAUTHORIZED` | Missing or invalid API key / JWT |
| `429` | `RATE_LIMITED` | Rate limit exceeded |
| `500` | `INTERNAL_ERROR` | Server error |