# Stats API

Stream and widget statistics.

Authenticate with a [personal token](/docs/api#personal-tokens) as `Authorization: Bearer pxp_...`; the operations are also [MCP tools](/docs/connect-ai) unless noted. The full machine-readable definition is in the [OpenAPI specification](https://pxstudio.cloud/api/v1/openapi.json).

| Operation | Method and path | Scope |
| --- | --- | --- |
| [Get last stream report](#get-last-stream-report) | `GET /stats/last-stream` | `account:read` |
| [List stream sessions](#list-stream-sessions) | `GET /stats/sessions` | `account:read` |
| [Get daily stats](#get-daily-stats) | `GET /stats/daily` | `account:read` |
| [List account activity](#list-account-activity) | `GET /activity` | `account:read` |
| [Get account activity stats](#get-account-activity-stats) | `GET /activity/stats` | `account:read` |

## Operations

### Get last stream report

```http Endpoint
GET /api/v1/stats/last-stream
```

Returns the most recent stream session: start/end, duration and counts of follows, subs, gifts, cheers, raids and donations.

**Scope:** `account:read` (Read your account) · **MCP tool:** `get_last_stream_report` · **Notes:** read only

::: tabs
@@ cURL
```bash
curl -X GET "https://pxstudio.cloud/api/v1/stats/last-stream" \
  -H "Authorization: Bearer $PX_TOKEN"
```
@@ JavaScript
```js
const res = await fetch('https://pxstudio.cloud/api/v1/stats/last-stream', {
  headers: {
    Authorization: `Bearer ${process.env.PX_TOKEN}`,
  },
});
if (!res.ok) throw new Error(`PX Studio API: ${res.status}`);
const data = await res.json();
```
:::

### List stream sessions

```http Endpoint
GET /api/v1/stats/sessions
```

Lists your recent stream sessions (start, end, duration and counts of follows, subs, gifts, cheers, raids and donations), newest first. The CSV export is on the stats page.

**Scope:** `account:read` (Read your account) · **MCP tool:** `list_stream_sessions` · **Notes:** read only

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `limit` | query | integer | optional | 1 to 50 |

::: tabs
@@ cURL
```bash
curl -X GET "https://pxstudio.cloud/api/v1/stats/sessions" \
  -H "Authorization: Bearer $PX_TOKEN"
```
@@ JavaScript
```js
const res = await fetch('https://pxstudio.cloud/api/v1/stats/sessions', {
  headers: {
    Authorization: `Bearer ${process.env.PX_TOKEN}`,
  },
});
if (!res.ok) throw new Error(`PX Studio API: ${res.status}`);
const data = await res.json();
```
:::

### Get daily stats

```http Endpoint
GET /api/v1/stats/daily
```

Returns your channel events per day for the last 1 to 90 days (follows, subs, resubs, gifted subs, cheers and bits, raids and raid viewers, donations and amounts), oldest first.

**Scope:** `account:read` (Read your account) · **MCP tool:** `get_daily_stats` · **Notes:** read only

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `days` | query | integer | optional | 1 to 90 |

::: tabs
@@ cURL
```bash
curl -X GET "https://pxstudio.cloud/api/v1/stats/daily" \
  -H "Authorization: Bearer $PX_TOKEN"
```
@@ JavaScript
```js
const res = await fetch('https://pxstudio.cloud/api/v1/stats/daily', {
  headers: {
    Authorization: `Bearer ${process.env.PX_TOKEN}`,
  },
});
if (!res.ok) throw new Error(`PX Studio API: ${res.status}`);
const data = await res.json();
```
:::

### List account activity

```http Endpoint
GET /api/v1/activity
```

Lists the stream events of your account across all overlays (follows, subs, cheers, raids, tips, redemptions, hype trains), newest first, with optional kind, source and search. Names and messages come from viewers.

**Scope:** `account:read` (Read your account) · **MCP tool:** `list_account_activity` · **Notes:** read only

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `limit` | query | integer | optional | 1 to 50 |
| `kind` | query | `all`, `follow`, `sub`, `cheer`, `raid`, `tip`, `redemption`, `hype` | optional |  |
| `source` | query | `all`, `twitch`, `kick`, `kofi` | optional |  |
| `q` | query | string | optional | Up to 60 characters |
| `beforeId` | query | integer | optional | Older page: the smallest id you have. At least 1 |

::: tabs
@@ cURL
```bash
curl -X GET "https://pxstudio.cloud/api/v1/activity" \
  -H "Authorization: Bearer $PX_TOKEN"
```
@@ JavaScript
```js
const res = await fetch('https://pxstudio.cloud/api/v1/activity', {
  headers: {
    Authorization: `Bearer ${process.env.PX_TOKEN}`,
  },
});
if (!res.ok) throw new Error(`PX Studio API: ${res.status}`);
const data = await res.json();
```
:::

### Get account activity stats

```http Endpoint
GET /api/v1/activity/stats
```

Returns the counts of the current stream session across your own account: follows, subs, cheers and bits, raids and raid viewers, tips, redemptions and hype trains. For an overlay shared with you, get_activity_stats returns the overlay owner's numbers instead.

**Scope:** `account:read` (Read your account) · **MCP tool:** `get_account_activity_stats` · **Notes:** read only

::: tabs
@@ cURL
```bash
curl -X GET "https://pxstudio.cloud/api/v1/activity/stats" \
  -H "Authorization: Bearer $PX_TOKEN"
```
@@ JavaScript
```js
const res = await fetch('https://pxstudio.cloud/api/v1/activity/stats', {
  headers: {
    Authorization: `Bearer ${process.env.PX_TOKEN}`,
  },
});
if (!res.ok) throw new Error(`PX Studio API: ${res.status}`);
const data = await res.json();
```
:::