Unified Events API · Self-describing routes

Event Metrics API

This page helps you explore the Event Metrics API and turn endpoints into working StreamElements commands. Start by checking which events and methods exist, then use the Command Lab to build and preview the exact reply your bot would send in chat.

Open Command Lab StreamElements Docs
Discovery Flow List events → inspect methods → describe parameters → generate command
Primary Routes GET /api/v1/events and GET /api/v1/event/{eventId}
Chatbot Friendly Use ?format=text when you want reply-ready command output.

Getting Started

This API is self-describing. Start with event discovery, then drill into event-specific method paths and parameter metadata.

3-step flow
1

List available events

Fetch the event index first so you know which event IDs are currently valid.

GET /api/v1/events
2

Inspect one event

Every event declares its own methods, so inspect the event payload to discover what routes it supports.

GET /api/v1/event/peanuts-wasteland-s1
3

Describe one method

Add ?describe=true to a method route when you need parameter metadata before generating a command.

GET /api/v1/event/peanuts-wasteland-s1/leaderboard/pvp/player_kills_total?describe=true
4

Use text output for chat

Plain-text output keeps StreamElements replies clean. Optional parameters can be added only when you need them.

?format=text&top=10&competitor=name

Response Shapes

These examples show how method discovery and method description are structured.

Event-driven methods

Inspect event metadata and methods

{
    "title": "...",
    "date": {
        "start": "ISO",
        "end": "ISO"
    },
    "owner": {
        "href": "https://...",
        "name": "..."
    },
    "methods": {
        "farm": {
            "description": "...",
            "parameters": []
        },
        "leaderboard/pvp/player_kills_total": {
            "description": "...",
            "parameters": []
        }
    }
}

Describe a single method

{
    "description": "Leaderboard of Kills ⚔️",
    "parameters": [
        {
            "name": "format",
            "description": "If 'text' is provided, the response will be returned as a text/plain string, otherwise it will be returned as the default application/json.",
            "required": false,
            "type": "string",
            "values": [
                "text"
            ]
        },
        {
            "name": "top",
            "description": "The number of top results to return.",
            "required": false,
            "type": "number"
        },
        {
            "name": "competitor",
            "description": "If provided, instead of returning the full leaderboard, the response will include only the specified competitor's data versus the leader.",
            "required": false,
            "type": "string",
            "values": [
                "text"
            ]
        }
    ]
}

Parameters marked optional can be omitted. Common method parameters include format for plain-text output, top to limit results, and competitor to compare one competitor against the leader.

  • format · string · optional
  • top · number · optional
  • competitor · string · optional

StreamElements Examples

Reference examples for common command setups using StreamElements Custom API variables.

!farm

Use a player-aware farm endpoint with chat-friendly formatting controls.

Reply
Moderator Command

Tip: $(queryescape ${1|all}) lets the same command handle both !farm and !farm wood. If no extra argument is supplied it defaults to all, and if a stat is supplied it passes that specific value through, so users can view everything or one stat without needing a second command.

!team

Example of getting the current team information of a player.

Reply
Moderator Command

For setup and syntax details, refer to the official StreamElements documentation: Custom API variables.