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

# Statistics

> Get aggregated metrics and usage statistics for your logs.

## Get Statistics

**GET** `/v1/stats`

Retrieve aggregated log counts grouped by time or source.

### Query Parameters

| Parameter     | Type   | Default    | Description                          |
| ------------- | ------ | ---------- | ------------------------------------ |
| `from`        | string | 7 days ago | Start date (YYYY-MM-DD)              |
| `to`          | string | Today      | End date (YYYY-MM-DD)                |
| `groupBy`     | string | `day`      | Grouping: `hour`, `day`, or `source` |
| `source`      | string | -          | Filter by source                     |
| `environment` | string | -          | Filter by environment                |
| `dataset`     | string | -          | Filter by dataset                    |

### Response

**Grouped by day (default):**

```json theme={null}
{
  "stats": [
    {
      "date": "2024-01-02",
      "debug": 1500,
      "info": 8500,
      "warn": 350,
      "error": 150,
      "total": 10500
    },
    {
      "date": "2024-01-01",
      "debug": 1200,
      "info": 7800,
      "warn": 280,
      "error": 120,
      "total": 9400
    }
  ],
  "totals": {
    "debug": 2700,
    "info": 16300,
    "warn": 630,
    "error": 270,
    "total": 19900
  },
  "period": {
    "from": "2024-01-01",
    "to": "2024-01-02",
    "groupBy": "day"
  }
}
```

**Grouped by hour:**

```json theme={null}
{
  "stats": [
    {
      "date": "2024-01-02",
      "hour": 14,
      "debug": 100,
      "info": 450,
      "warn": 20,
      "error": 5,
      "total": 575
    }
  ],
  "totals": { "..." : "..." },
  "period": {
    "groupBy": "hour"
  }
}
```

**Grouped by source:**

```json theme={null}
{
  "stats": [
    {
      "source": "api-server",
      "debug": 1500,
      "info": 8000,
      "warn": 300,
      "error": 100,
      "total": 9900
    },
    {
      "source": "worker",
      "debug": 500,
      "info": 2000,
      "warn": 50,
      "error": 20,
      "total": 2570
    }
  ],
  "totals": { "..." : "..." },
  "period": {
    "groupBy": "source"
  }
}
```

### Examples

**Last 7 days by day:**

```bash theme={null}
curl -X GET "https://timberlogs-ingest.enaboapps.workers.dev/v1/stats" \
  -H "Authorization: Bearer tb_live_xxxxxxxxxxxxx"
```

**Last 24 hours by hour:**

```bash theme={null}
curl -X GET "https://timberlogs-ingest.enaboapps.workers.dev/v1/stats?from=2024-01-01&to=2024-01-02&groupBy=hour" \
  -H "Authorization: Bearer tb_live_xxxxxxxxxxxxx"
```

**By source:**

```bash theme={null}
curl -X GET "https://timberlogs-ingest.enaboapps.workers.dev/v1/stats?groupBy=source" \
  -H "Authorization: Bearer tb_live_xxxxxxxxxxxxx"
```

**Filter by environment:**

```bash theme={null}
curl -X GET "https://timberlogs-ingest.enaboapps.workers.dev/v1/stats?environment=production" \
  -H "Authorization: Bearer tb_live_xxxxxxxxxxxxx"
```

## Get Summary

**GET** `/v1/stats/summary`

Quick overview of today's activity compared to yesterday.

### Response

```json theme={null}
{
  "today": {
    "debug": 500,
    "info": 3500,
    "warn": 150,
    "error": 50,
    "total": 4200
  },
  "comparison": {
    "yesterdayTotal": 3800,
    "changePercent": 11,
    "trend": "up"
  }
}
```

| Field                         | Description                      |
| ----------------------------- | -------------------------------- |
| `today.total`                 | Total logs today                 |
| `today.debug/info/warn/error` | Counts by level                  |
| `comparison.yesterdayTotal`   | Yesterday's total for comparison |
| `comparison.changePercent`    | Percentage change from yesterday |
| `comparison.trend`            | `up`, `down`, or `stable`        |

### Example

```bash theme={null}
curl -X GET "https://timberlogs-ingest.enaboapps.workers.dev/v1/stats/summary" \
  -H "Authorization: Bearer tb_live_xxxxxxxxxxxxx"
```

## Error Responses

**401 Unauthorized** - Invalid or missing API key

```json theme={null}
{
  "error": "Invalid API key"
}
```

**How to resolve:** All stats endpoints require authentication. Ensure your `Authorization` or `X-API-Key` header is included and valid. See [Authentication](/api-reference/authentication) for details on API key format and usage.

## Examples

### Dashboard Metrics

Display key metrics in your application dashboard:

```typescript theme={null}
const response = await fetch(
  'https://timberlogs-ingest.enaboapps.workers.dev/v1/stats/summary',
  { headers: { Authorization: `Bearer ${apiKey}` } }
)
const { today, comparison } = await response.json()

console.log(`Today: ${today.total} logs`)
console.log(`Errors: ${today.error}`)
console.log(`Trend: ${comparison.trend} (${comparison.changePercent}%)`)
```

### Error Rate Monitoring

Track error rates over time:

```typescript theme={null}
const response = await fetch(
  'https://timberlogs-ingest.enaboapps.workers.dev/v1/stats?groupBy=day',
  { headers: { Authorization: `Bearer ${apiKey}` } }
)
const { stats } = await response.json()

for (const day of stats) {
  const errorRate = ((day.error / day.total) * 100).toFixed(2)
  console.log(`${day.date}: ${errorRate}% errors`)
}
```

### Source Comparison

Compare log volume across services:

```typescript theme={null}
const response = await fetch(
  'https://timberlogs-ingest.enaboapps.workers.dev/v1/stats?groupBy=source',
  { headers: { Authorization: `Bearer ${apiKey}` } }
)
const { stats } = await response.json()

for (const source of stats) {
  console.log(`${source.source}: ${source.total} logs`)
}
```