API Docs

API Documentation for accessing ChatStats.live statistics data.

Notice:
For privacy and data safety, all usernames shown in API examples have been redacted and replaced with random prominent Twitch figures. API results for your queries will contain real usernames as appropriate, but documentation and public examples are anonymized.

Base URL

The base URL for all API requests.

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

Get statistics for a streamer for the current month or a specific month.

Query Parameters

Parameter Type Required Description
username string Required Twitch username (In lowercase)
month string Optional Month in format YYYY-MM, MMMYYYY (e.g., "dec2025"), or MM/YYYY
fields string Optional Comma-separated list of fields to return (e.g., summary,topChatters). Supports nested fields like summary.totalMessages

Example Requests

# Current month stats
GET /api/v1/stats?username=pokimane

# Specific month stats
GET /api/v1/stats?username=pokimane&month=2025-12
GET /api/v1/stats?username=pokimane&month=dec2025
GET /api/v1/stats?username=pokimane&month=12/2025

# Request only specific fields
GET /api/v1/stats?username=pokimane&fields=summary,topChatters
GET /api/v1/stats?username=pokimane&fields=summary.totalMessages

Example Response

{
  "success": true,
  "data": {
    "month": "12",
    "year": "2025",
    "summary": {
      "totalMessages": 8972,
      "totalChatters": 301,
      "totalStreams": 7
    },
    "topChatters": [
      {
        "username": "mizkif",
        "messages": 762,
        "isVIP": false,
        "isMod": false
      }
    ],
    "emotes": [
      {
        "name": "OMEGALUL",
        "count": 184,
        "position": 1
      }
    ]
  },
  "links": {
    "self": "https://chatstats.live/api/v1/stats?username=pokimane",
    "archives": "https://chatstats.live/api/v1/archives?username=pokimane",
    "top_chatters": "https://chatstats.live/api/v1/top-chatters?username=pokimane",
    "emotes": "https://chatstats.live/api/v1/emotes?username=pokimane"
  },
  "meta": {
    "username": "pokimane",
    "month": "12",
    "year": "2025",
    "generated_at": "2025-12-31T23:59:59.000Z"
  }
}

Note: All responses include HATEOAS links in the links object for easy navigation to related resources. Responses also include a X-Request-ID header for request tracing.

GET /api/v1/top-chatters

Get the list of top chatters for a streamer.

Query Parameters

Parameter Type Required Description
username string Required Twitch username
month string Optional Month in format YYYY-MM, MMMYYYY, or MM/YYYY
limit number Optional Maximum number of chatters to return (default: all, max: 100)
offset number Optional Number of results to skip for pagination (default: 0)

Example Requests

# All top chatters for current month
GET /api/v1/top-chatters?username=xqc

# Top 10 chatters for specific month
GET /api/v1/top-chatters?username=xqc&month=2025-12&limit=10

# Paginated results (next 10 after first 10)
GET /api/v1/top-chatters?username=xqc&limit=10&offset=10

Example Response

{
  "success": true,
  "data": {
    "chatters": [
      {
        "username": "hasanabi",
        "messages": 504,
        "isVIP": false,
        "isMod": true
      }
    ],
    "total": 168,
    "returned": 10
  },
  "links": {
    "self": "https://chatstats.live/api/v1/top-chatters?username=xqc&limit=10&offset=0",
    "first": "https://chatstats.live/api/v1/top-chatters?username=xqc&limit=10&offset=0",
    "next": "https://chatstats.live/api/v1/top-chatters?username=xqc&limit=10&offset=10",
    "last": "https://chatstats.live/api/v1/top-chatters?username=xqc&limit=10&offset=160"
  },
  "pagination": {
    "total": 168,
    "limit": 10,
    "offset": 0,
    "returned": 10
  },
  "meta": {
    "username": "xqc",
    "month": "12",
    "year": "2025",
    "generated_at": "2025-12-31T23:59:59.000Z"
  }
}

Note: isVIP is true if the user is marked as a VIP (bold in HTML). isMod is true if the user is marked as a Mod (italic in HTML). Mod and VIP highlighting are only available for users with a ChatStats.live Pro subscription.

GET /api/v1/emotes

Get emote usage statistics for a streamer.

Query Parameters

Parameter Type Required Description
username string Required Twitch username
month string Optional Month in format YYYY-MM, MMMYYYY, or MM/YYYY

Example Requests

# Current month emotes
GET /api/v1/emotes?username=ludwig

# Specific month emotes
GET /api/v1/emotes?username=ludwig&month=2025-12

Example Response

{
  "success": true,
  "data": {
    "emotes": [
      {
        "name": "ludwigW",
        "count": 99,
        "position": 1
      },
      {
        "name": "KEKW",
        "count": 56,
        "position": 2
      }
    ],
    "total": 10
  },
  "links": {
    "self": "https://chatstats.live/api/v1/emotes?username=ludwig",
    "archives": "https://chatstats.live/api/v1/archives?username=ludwig",
    "top_chatters": "https://chatstats.live/api/v1/top-chatters?username=ludwig",
    "stats": "https://chatstats.live/api/v1/stats?username=ludwig"
  },
  "meta": {
    "username": "ludwig",
    "month": "12",
    "year": "2025",
    "generated_at": "2025-12-31T23:59:59.000Z"
  }
}

Note: position indicates ranking: 1 = first place, 2 = second place, 3 = third place. Only top 3 emotes are typically available in the HTML. Emote Statistics are only available for users with a ChatStats.live Pro subscription.

GET /api/v1/archives

Get a list of available archive months for a streamer.

Query Parameters

Parameter Type Required Description
username string Required Twitch username

Example Request

GET /api/v1/archives?username=shroud

Example Response

{
  "success": true,
  "data": {
    "archives": [
      {
        "month": "12",
        "year": "2025",
        "monthName": "dec",
        "format": "2025-12",
        "display": "December 2025"
      },
      {
        "month": "11",
        "year": "2025",
        "monthName": "nov",
        "format": "2025-11",
        "display": "November 2025"
      }
    ],
    "total": 2
  },
  "links": {
    "self": "https://chatstats.live/api/v1/archives?username=shroud",
    "top_chatters": "https://chatstats.live/api/v1/top-chatters?username=shroud",
    "emotes": "https://chatstats.live/api/v1/emotes?username=shroud",
    "stats": "https://chatstats.live/api/v1/stats?username=shroud"
  },
  "meta": {
    "username": "shroud",
    "streamerPath": "shroud",
    "generated_at": "2025-12-31T23:59:59.000Z"
  }
}

Note: Archives are only available for users with a ChatStats.live Plus or Pro subscription.

Error Responses

All endpoints return errors in a consistent format:

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

Error Codes

Error Code Description HTTP Status
USER_NOT_FOUND Streamer doesn't exist or has no data 404
MONTH_NOT_AVAILABLE Requested month has no data available 404
INVALID_USERNAME Username format is invalid 400
INVALID_MONTH Month format is invalid 400
INVALID_LIMIT Limit parameter is invalid (must be 1-100) 400
INVALID_OFFSET Offset parameter is invalid (must be >= 0) 400
PARSING_ERROR Failed to parse HTML data 500
FILE_NOT_FOUND Requested file not found 404
SERVER_ERROR Internal server error 500
METHOD_NOT_ALLOWED HTTP method not allowed 405

Error Response Format

{
  "success": false,
  "error": {
    "message": "Error description",
    "code": "ERROR_CODE",
    "details": {
      "provided": "value",
      "allowed_methods": ["GET"]
    }
  },
  "meta": {
    "generated_at": "2025-12-31T23:59:59.000Z",
    "request_id": "req_1234567890_abc123"
  }
}

Note: Error responses include a request_id in the meta object (also available in the X-Request-ID response header) for tracing and debugging purposes.

Username Mapping

Some Twitch usernames map to different folder paths, this is usually because the user has a vanity URL set up: below are some examples of names that are not the same as the Twitch username. note that in these cases, either the Twitch username or the vanity name set by the user can be used to access the data.

Twitch Username Folder Path
pokimane poki
xqcow xqc
ludwigarghen ludwig

If a username doesn't have a mapping, it's used as-is (lowercase).

Code Examples

JavaScript/Fetch

// Get current month stats
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

# Get stats for current month
curl "https://chatstats.live/api/v1/stats?username=shroud"

# Get top 5 chatters for December 2025
curl "https://chatstats.live/api/v1/top-chatters?username=shroud&month=2025-12&limit=5"

# Get available archives
curl "https://chatstats.live/api/v1/archives?username=shroud"

Python

import requests

# Get current month stats
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']}")