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

# Analytics

> Query campaign performance KPIs and time-series activity data via the ColdSend API.

The Analytics API gives you programmatic access to your workspace's email performance data — aggregate KPIs across all campaigns, per-campaign breakdowns, and a daily time-series timeline you can pipe directly into your own dashboards.

## API Endpoints

| Method  | Endpoint                        | Description                                      |
| ------- | ------------------------------- | ------------------------------------------------ |
| **GET** | `/analytics/campaigns`          | Aggregate KPIs and per-campaign breakdown        |
| **GET** | `/analytics/campaigns/timeline` | Daily time-series of sent/opened/replied/bounced |

<Info>
  Both endpoints require the `campaigns:read` scope.
</Info>

***

## Get Campaign Analytics

**GET** `/api/public/v1/analytics/campaigns`

Returns workspace-wide KPIs and a per-campaign breakdown. Optionally filter by campaign status or a date range.

### Query Parameters

| Parameter   | Type   | Description                                                                                  |
| ----------- | ------ | -------------------------------------------------------------------------------------------- |
| `status`    | string | Filter to campaigns in a specific status: `DRAFT`, `ACTIVE`, `PAUSED`, `COMPLETED`, `FAILED` |
| `from_date` | string | ISO 8601 date — only campaigns launched on or after this date (e.g. `2024-01-01`)            |
| `to_date`   | string | ISO 8601 date — only campaigns launched on or before this date                               |

```python theme={null}
import requests

response = requests.get(
    "https://api.coldsend.pro/api/public/v1/analytics/campaigns",
    headers={"X-API-Key": api_key},
    params={
        "status": "COMPLETED",
        "from_date": "2024-01-01",
        "to_date": "2024-06-30"
    }
)
print(response.json())
```

### Response Format

```json theme={null}
{
  "workspace_kpis": {
    "total_campaigns": 12,
    "total_sends": 48320,
    "avg_open_rate": 0.34,
    "avg_reply_rate": 0.08,
    "avg_bounce_rate": 0.02
  },
  "campaigns": [
    {
      "campaign_id": "550e8400-e29b-41d4-a716-446655440000",
      "campaign_name": "Q1 Outreach",
      "status": "COMPLETED",
      "total_leads": 500,
      "total_sent": 498,
      "total_opened": 169,
      "total_replied": 40,
      "total_bounced": 2,
      "open_rate": 0.3394,
      "reply_rate": 0.0803,
      "bounce_rate": 0.004,
      "created_at": "2024-01-15T10:00:00Z"
    }
  ]
}
```

***

## Get Campaign Timeline

**GET** `/api/public/v1/analytics/campaigns/timeline`

Returns a contiguous daily series of email activity counts and derived rates. Defaults to the last **90 days** when no date range is supplied.

### Query Parameters

| Parameter   | Type   | Description                                                  |
| ----------- | ------ | ------------------------------------------------------------ |
| `from_date` | string | ISO 8601 date — start of the time window (e.g. `2024-01-01`) |
| `to_date`   | string | ISO 8601 date — end of the time window                       |

```python theme={null}
response = requests.get(
    "https://api.coldsend.pro/api/public/v1/analytics/campaigns/timeline",
    headers={"X-API-Key": api_key},
    params={
        "from_date": "2024-01-01",
        "to_date": "2024-03-31"
    }
)
print(response.json())
```

### Response Format

```json theme={null}
{
  "timeline": [
    {
      "date": "2024-01-15",
      "sent": 120,
      "opened": 41,
      "replied": 9,
      "bounced": 1,
      "open_rate": 0.3417,
      "reply_rate": 0.075,
      "bounce_rate": 0.0083
    },
    {
      "date": "2024-01-16",
      "sent": 85,
      "opened": 30,
      "replied": 7,
      "bounced": 0,
      "open_rate": 0.3529,
      "reply_rate": 0.0824,
      "bounce_rate": 0.0
    }
  ],
  "from_date": "2024-01-01",
  "to_date": "2024-03-31"
}
```

<Tip>
  Every day in the requested range is included in the response — days with zero activity return zeroed-out counts rather than being omitted. This makes it easy to chart a continuous series without client-side gap filling.
</Tip>

***

## Required Scopes

| Scope            | Grants Access To         |
| ---------------- | ------------------------ |
| `campaigns:read` | Both analytics endpoints |
| `campaigns:all`  | Both analytics endpoints |
| `*`              | Full workspace access    |

## Next Steps

<CardGroup cols={2}>
  <Card title="Campaigns Overview" icon="mail" href="/campaigns/overview">
    Manage campaigns and control their lifecycle.
  </Card>

  <Card title="Replies & Conversations" icon="message-square" href="/replies/overview">
    Access the unified reply inbox and thread details.
  </Card>
</CardGroup>