---
title: "Analytics API"
description: "Analytics in the OneSend API: 3 endpoints. Deliverability totals by provider, quota usage and the event log."
url: https://onesend.email/docs/api-reference/analytics/
---
[Docs](https://onesend.email/docs/) / [API reference](https://onesend.email/docs/api-reference/)

# Analytics

Deliverability totals by provider, quota usage and the event log.

Base URL `https://your-server.example` (your OneSend server). [Authentication](https://onesend.email/docs/api-reference/#authentication) and errors are described in the [overview](https://onesend.email/docs/api-reference/).

## Delivery, engagement and failover analytics

GET `/v1/analytics/summary`

Totals, rates, a time series and a per-provider breakdown (latency, top error codes). Filter by `provider` (provider id or connection id, comma separated), sending `domain`, `tag`, `template` and time range (default last 30 days).

**Authentication:** `Authorization: Bearer` with an API key or a session token.

### Parameters

| Name | In | Type | Description |
|---|---|---|---|
| `from` | query | `string` |  |
| `until` | query | `string` |  |
| `provider` | query | `string` |  |
| `domain` | query | `string` |  |
| `tag` | query | `string` |  |
| `template` | query | `string` |  |
| `interval` | query | `"hour" \| "day"` | Default "day". |

### Responses

`200` Success

```
{
  "totals": {
    "sent": number,
    "delivered": number,
    "bounced": number,
    "complained": number,
    "opened": number,
    "clicked": number,
    "failed": number,
    "failovers": number
  },
  "rates": {
    "delivery": number,
    "bounce": number,
    "complaint": number,
    "open": number,
    "click": number,
    "failover": number
  },
  "series": [{
    "sent": number,
    "delivered": number,
    "bounced": number,
    "complained": number,
    "opened": number,
    "clicked": number,
    "failed": number,
    "failovers": number,
    "t": string
  }],
  "byProvider": [{
    "sent": number,
    "delivered": number,
    "bounced": number,
    "complained": number,
    "opened": number,
    "clicked": number,
    "failed": number,
    "failovers": number,
    "connectionId": string,
    "provider": string,
    "name": string,
    "avgLatencyMs": number or null,
    "topErrors": [{ … }]
  }],
  "timezone": string
}
```

**Errors: 400, 401, 403, 404, 429, 500**

- `400` Invalid request: validation failed, a parameter is not allowed, the body is not valid JSON (`invalid_json`) or the pagination cursor is not valid (`invalid_cursor`). Type `invalid_request`.
- `401` Missing credentials (`unauthorized`), an unknown or revoked API key (`invalid_api_key`) or an expired session (`invalid_session`). Type `unauthorized`.
- `403` The API key's permission does not allow this operation (`insufficient_scope`; configuration needs an `admin` key), a test key was used outside its sandbox (`test_key_not_allowed`), a Conversion tracking key was used (`publishable_key`), or a cookie request is missing `X-OneSend-Client: dashboard` (`csrf_header_required`). Type `forbidden`.
- `404` The resource does not exist in this workspace (`not_found`)
- `429` Too many requests; retry after the time in the `Retry-After` header (`rate_limited`)
- `500` Unexpected server error (`internal`)

## Pooled and per-provider quota for today

GET `/v1/analytics/quota`

Includes a naive forecast of when today's pooled quota runs out at the current pace.

**Authentication:** `Authorization: Bearer` with an API key or a session token.

### Responses

`200` Success

```
{
  "pooled": {
    "dailyLimit": number or null,
    "usedToday": number,
    "remainingToday": number or null,
    "forecastExhaustAt": string or null,
    "excluded": [{
      "connectionId": string,
      "name": string,
      "reason": "sandbox" | "paused" | "error",
      "usedToday": number
    }]
  },
  "connections": [{
    "connectionId": string,
    "provider": string,
    "name": string,
    "dailyLimit": number or null,
    "usedToday": number,
    "monthlyLimit": number or null,
    "usedThisMonth": number,
    "health": number,
    "status": string
  }]
}
```

**Errors: 400, 401, 403, 404, 429, 500**

- `400` Invalid request: validation failed, a parameter is not allowed, the body is not valid JSON (`invalid_json`) or the pagination cursor is not valid (`invalid_cursor`). Type `invalid_request`.
- `401` Missing credentials (`unauthorized`), an unknown or revoked API key (`invalid_api_key`) or an expired session (`invalid_session`). Type `unauthorized`.
- `403` The API key's permission does not allow this operation (`insufficient_scope`; configuration needs an `admin` key), a test key was used outside its sandbox (`test_key_not_allowed`), a Conversion tracking key was used (`publishable_key`), or a cookie request is missing `X-OneSend-Client: dashboard` (`csrf_header_required`). Type `forbidden`.
- `404` The resource does not exist in this workspace (`not_found`)
- `429` Too many requests; retry after the time in the `Retry-After` header (`rate_limited`)
- `500` Unexpected server error (`internal`)

## Event log

GET `/v1/events`

Every lifecycle event (queued, sent, delivered, bounced, failover, opened, received, …), newest first.

**Authentication:** `Authorization: Bearer` with an API key or a session token.

### Parameters

| Name | In | Type | Description |
|---|---|---|---|
| `type` | query | `string` |  |
| `messageId` | query | `string` |  |
| `provider` | query | `string` |  |
| `from` | query | `string (date-time)` |  |
| `cursor` | query | `string` |  |
| `limit` | query | `integer` | Default 100. 1 to 500. |

### Responses

`200` Success

```
{
  "data": [{
    "id": string,
    "type": string,
    "messageId": string or null,
    "provider": string or null,
    "connectionId": string or null,
    "recipient": string or null,
    "data": object or null,
    "occurredAt": string
  }],
  "nextCursor": string or null
}
```

**Errors: 400, 401, 403, 404, 429, 500**

- `400` Invalid request: validation failed, a parameter is not allowed, the body is not valid JSON (`invalid_json`) or the pagination cursor is not valid (`invalid_cursor`). Type `invalid_request`.
- `401` Missing credentials (`unauthorized`), an unknown or revoked API key (`invalid_api_key`) or an expired session (`invalid_session`). Type `unauthorized`.
- `403` The API key's permission does not allow this operation (`insufficient_scope`; configuration needs an `admin` key), a test key was used outside its sandbox (`test_key_not_allowed`), a Conversion tracking key was used (`publishable_key`), or a cookie request is missing `X-OneSend-Client: dashboard` (`csrf_header_required`). Type `forbidden`.
- `404` The resource does not exist in this workspace (`not_found`)
- `429` Too many requests; retry after the time in the `Retry-After` header (`rate_limited`)
- `500` Unexpected server error (`internal`)
