Last edited Apr 17, 2026

API overview

Tags:apioverview

Notice: For privacy and data safety, usernames shown in public examples are anonymized. Live API responses use real usernames when appropriate.

Base URL

All versioned endpoints share:

https://chatstats.live/api/v1/

Endpoints at a glance

Method	Path	Summary
GET	`/stats`	Streamer statistics for the current or a chosen month
GET	`/top-chatters`	Ranked chatters with optional pagination
GET	`/emotes`	Emote usage for the month
GET	`/archives`	Months that have saved data for a streamer

Shared response shape

Successful responses include:

success: true and a data object
links HATEOAS URLs to related resources
meta context such as username, month, year, and generated_at

Responses also include an X-Request-ID header for tracing (mirrored in some error payloads as meta.request_id).

Errors

All endpoints use a consistent error envelope when success is false:

{
  "success": false,
  "error": {
    "message": "Error description",
    "code": "ERROR_CODE"
  },
  "meta": {
    "generated_at": "2025-12-31T23:59:59.000Z"
  }
}

Optional error.details may include fields such as provided or allowed_methods.

Error codes

Code	HTTP	Meaning
`USER_NOT_FOUND`	404	Streamer not found or no data
`MONTH_NOT_AVAILABLE`	404	No data for requested month
`INVALID_USERNAME`	400	Username format invalid
`INVALID_MONTH`	400	Month format invalid
`INVALID_LIMIT`	400	Limit not in 1–100
`INVALID_OFFSET`	400	Offset must be ≥ 0
`PARSING_ERROR`	500	Failed to parse source data
`FILE_NOT_FOUND`	404	Requested file missing
`SERVER_ERROR`	500	Internal error
`METHOD_NOT_ALLOWED`	405	Wrong HTTP method

See the dedicated errors reference for the same table with prose notes.

Username → folder mapping

Some Twitch logins map to a different on-disk folder (often vanity URLs). Either the Twitch username or the folder name may be used in API calls:

Twitch username	Folder path
`pokimane`	`poki`
`xqcow`	`xqc`
`ludwigarghen`	`ludwig`

If there is no mapping, the username is used as-is (lowercase). More detail: Username mapping.

Code examples

JavaScript (fetch)

const response = await fetch('https://chatstats.live/api/v1/stats?username=shroud');
const data = await response.json();

if (data.success) {
  console.log(`Total messages: ${data.data.summary.totalMessages}`);
  console.log(`Top chatter: ${data.data.topChatters[0].username}`);
} else {
  console.error(`Error: ${data.error.message}`);
}

cURL

curl "https://chatstats.live/api/v1/stats?username=shroud"
curl "https://chatstats.live/api/v1/top-chatters?username=shroud&month=2025-12&limit=5"
curl "https://chatstats.live/api/v1/archives?username=shroud"

Python

import requests

response = requests.get(
    "https://chatstats.live/api/v1/stats",
    params={"username": "shroud"},
)
data = response.json()

if data["success"]:
    print(f"Total messages: {data['data']['summary']['totalMessages']}")
else:
    print(f"Error: {data['error']['message']}")

More copy-paste samples: Code examples.

Next steps

Open an endpoint page in the sidebar for parameters, examples, and subscription-related notes.