People and identify
See who uses your app, who is online or active, who is new, and who has gone quiet, and set properties on a person with the identify API.
Get Butters keeps a People list for every project. It lists everyone your app has ever attached to an event through a user_id: their user id, when you first saw them, when you last saw them, how many events they've sent, and any properties you've set on them. You can filter it to who is online, active, new, or drifting away.
Where to find it
Open a project and click People in the project navigation. People are listed 50 per page, most recently seen first. To find someone, type the start of their user id into Search by user id and click Search. The search keeps whichever filter tab you're on.
You can also get there from Charts: every stat in the People section opens the People list filtered to exactly the people that stat counts.
Filter tabs
All shows everyone the project knows about.
Online now shows people who sent an event in the last 5 minutes. There is no live presence signal, so "online" means "recently sent an event". If your app only sends events on signup or checkout, most active users will never show here.
Active today shows people with an event since midnight UTC today.
Active 30 days shows people with an event in the last 30 days, counting today.
New shows people whose first event falls in the window, newest first. Opening it from Charts uses the window you were viewing there, for example New, 7 days.
Drifting shows people you haven't seen in a while. Pick 30 days, 60 days, or 90 days. The list starts with the people who went quiet most recently, since they're the easiest to win back. People you identified but who never sent an event aren't included.
People on the Charts page
Once a project has at least one person, Charts shows a People section above the event charts:
- Online now: people with an event in the last 5 minutes.
- Daily active: distinct users with an event today.
- Monthly active: distinct users with an event in the last 30 days.
- New users: people whose first event falls inside the chart window.
- All users: everyone in the People list.
Click any of them to open the matching People tab. Below the stats, Daily Active Users and Monthly Active Users chart those counts for each day of the window you pick with the 1 days, 7 days, 30 days, or 90 days tabs. Each monthly point always looks back 30 days, even on the 7-day view.
Daily and monthly active counts come from your events, so they drop as old events are removed by your plan's retention. All users and New users come from the People list and don't.
How people are created
A person shows up automatically the first time an event for that project carries a user_id. This works the same way whether the event comes from the API, from the dashboard playground, from an incoming webhook, or from an import. Every later event with the same user_id updates that person's last seen time and event count. Nothing about this requires calling identify: sending events with a user_id is enough.
The Events column is an all-time count, so it can be higher than what your feed still shows after retention removes old events.
Setting properties with identify
If you want to record facts about a person, not just that they exist, call the identify endpoint from your app:
POST /api/identify with a body like:
{ "user_id": "user-456", "properties": { "plan": "pro", "email": "maria@example.com" } } identify does not create an event and does not count against your monthly event quota. It only sets or updates properties on the person. New properties are merged into whatever the person already has, so calling identify again with just one field leaves the rest alone. Setting a property to null stores null; it does not remove the property.
A person created only by identify has no first or last seen time until they send an event, so they appear under All but not in the activity tabs.
See the API Reference, Identify section, for the exact request and error format.
Trust warning: only set what you can afford to lose
If you call identify from a browser using a publishable key, treat everything it sends as unverified. Anyone who can run JavaScript on your page, or who can craft the HTTP request by hand, can call identify with any user_id and any properties they like. There is nothing stopping them from claiming to be a different user or inventing property values.
Because of this, never set a property that matters from a publishable key: not a plan, not billing status, not anything used to grant access, and not anything that will trigger an alert. Set those from your own server using a secret key, where you control both the user_id and the values going in. Reserve publishable-key identify calls for cosmetic details, like a theme preference or last-viewed page.
identify records what a client claims about a user. It is not authentication, and it does not prove the request came from that user.
Troubleshooting
There's no People section on Charts: the project has never seen a person. Send events with a user_id, or call identify, and the section appears.
"Nobody matches this filter yet.": no one fits the tab you picked. For Online now, that just means nobody sent an event in the last 5 minutes.
"No people yet.": the project has no people at all. Add a user_id to your events or call identify.
"user_id is required": you called identify without a user_id, or sent an empty one. Every identify call needs a user_id between 1 and 200 characters.
"properties must be a JSON object": properties was missing an object shape, for example an array or a plain string. Send properties as a JSON object of key-value pairs, or leave it out entirely.
"properties must serialize to at most 65536 bytes": the properties object is too large. Trim it to the fields you actually need; identify isn't meant to store large blobs.
A publishable key request returns 404 Project not found: publishable keys write to one project only. If you pass a project field naming a different project, the call is rejected. Omit project entirely when using a publishable key.