Actors

Attach an _actor to your events to follow the person or server behind them and build actor timelines and retention.

An actor is the person or server behind your events. You identify an actor by attaching an _actor value to the events you send, like a user id, an account id, or a server name. Once events carry an _actor, TopStats can group them together to show you everything that one actor did.

Events with no _actor are anonymous. They still count in your charts, but they never show up in the Actors view and cannot be tied to a single person or server over time.

Why attach an actor?

An _actor is what turns a pile of separate events into a story about one user or server. It powers the Actors page, the per-actor timeline, and retention grids that measure who came back.

The `_actor` field

_actor is an optional, reserved field on the event payload. Reserved fields start with _ so they never clash with your own properties.

Prop

Type

Keep it short

An _actor is a string of at most 256 characters. Use a stable id (like user_123) so the same person or server always maps to the same actor.

Giving an actor a readable name

A stable id makes a good _actor but a poor thing to read. Send an optional _actorLabel alongside it to attach a human-readable name, up to 256 characters.

{
  "name": "purchase",
  "_actor": "user_123",
  "_actorLabel": "Ada Lovelace"
}

The label is display only. It never changes who the actor is, so identity, grouping and retention all keep working off _actor exactly as before. That means you can start sending labels at any point without disturbing the history you already have.

The newest label you have sent wins. Events that leave _actorLabel out do not clear the name, so you only need to send it when it is set or when it changes.

Labels are not identity

Two actors with the same label are still two different actors. If you want events to count as the same person, they have to share the same _actor value.

Attaching an actor

Add _actor alongside name and properties when you send an event to POST /v1/events. See Sending events for the full payload.

curl -X POST https://topstats.gg/v1/events \
  -H "Authorization: Bearer ts_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "player_join",
    "properties": { "map": "desert" },
    "_actor": "user_123"
  }'

Building a timeline and retention

The value of an actor comes from sending many events with the same _actor over time. Each event with _actor: "user_123" is added to that actor's history, no matter when it happened or what its name is.

Here several events share one actor. Sent this way, they build up user_123's timeline, and because they span more than one day they also feed a retention grid that measures whether the actor came back.

{
  "events": [
    { "name": "player_join", "_actor": "user_123", "_timestamp": "2026-07-20T09:00:00Z" },
    { "name": "level_complete", "_actor": "user_123", "properties": { "level": 3 }, "_timestamp": "2026-07-20T09:14:00Z" },
    { "name": "purchase", "_actor": "user_123", "properties": { "amount": 9.99 }, "_timestamp": "2026-07-22T18:30:00Z" }
  ]
}

This uses the batch format (an object with an events array). You do not have to batch them; sending the same three events one at a time builds the exact same actor history.

The Actors page

The Actors page (in the main navigation) is a ranked list of everyone behind your events. It lists actors by event count, with:

The actor key (the _actor value you sent). When you have sent an _actorLabel, the label is shown instead and the raw key sits underneath it.
The total events that actor has.
The last-seen time.

Switch the environment and time range at the top of the page. The list shows 50 actors by default and is capped at 200.

The actor timeline

Click an actor to open their timeline. It shows:

Total events, plus first-seen and last-seen times.
A timeline of that actor's most recent events (up to 100 within the selected range), each with its name, time, source, and properties.

Array (list) properties are shown as their values together, so you can see the full context of each event at a glance. Use the timeline to follow one user or server step by step and understand exactly what they did.