State and decisioning

The current console splits operational visibility into four related pages:

• Entities
• Sessions
• Events
• Decisions

The simple difference between these pages

Page	What it tells you
Entities	What Esper knows about a long-lived identity
Sessions	What Esper knows about a shorter-lived activity window
Events	What arrived
Decisions	What Esper decided

Entities

The entity summary list currently shows:

• entity_id
• decision_count
• last_seen_at

When an operator clicks Inspect, the frontend fetches a live entity state snapshot containing:

• entity_id
• source_id
• event_count
• first_seen_at
• last_seen_at

Endpoint used:

GET /tenants/{tenant_id}/entities/{entity_id}/state

What this means in practice:

• an entity is usually the "who" Esper is tracking
• use this page when you want to understand history for a person, account, or other durable identity
• decision_count tells you how often that entity has triggered recorded outcomes

Sessions

The session summary list currently shows:

• session_id
• event_count
• last_seen_at

The live session state snapshot contains:

• session_id
• entity_id
• event_count
• first_seen_at
• last_seen_at

Endpoint used:

GET /tenants/{tenant_id}/sessions/{session_id}/state

What this means in practice:

• a session is usually the "current burst of activity"
• use it when behavior may look normal over months but suspicious over minutes
• event_count helps you see whether a session is unusually active

Events

The events page is a tenant-scoped history feed. The list view displays:

• event_id
• source_id
• payload field count
• recorded_at

The current page does not render the full payload body, only summary metadata.

How to read the event fields:

Field	Meaning
event_id	The unique record for that event
source_id	Which sending system produced it
payload field count	Rough size of the captured payload
recorded_at	When the event was stored

Use events when you are asking:

• Did the traffic arrive?
• Which system sent it?
• Did it appear at the expected time?

Decisions

The decisions page displays:

• decision_id
• event_id
• entity_id
• session_id
• final_decision
• recorded_at

Decision tone in the UI is currently mapped like this:

• Block -> danger
• Challenge -> warning
• Allow and Observe -> success

This page is useful for confirming how replayed or live traffic resolves after encoding and rule evaluation.

How to read the important fields:

Field	Meaning
decision_id	The unique record for the decision
event_id	Which event triggered the decision
entity_id	Which tracked identity this decision belongs to
session_id	Which session this decision belongs to
final_decision	The actual outcome Esper returned
recorded_at	When the decision was written

If you need to explain "why did Esper do this?", the practical flow is:

1. Start with the decision.
2. Find the related entity or session.
3. Review the event source and timing.
4. Check whether a rule or replay change likely caused the outcome.