SecureGate Docs

Presence tracking — entry/exit logs, room occupancy, dwell time, and peak detection

Overview

The timeline records every face recognition event that occurs on entry and exit cameras. Each entry captures who was detected, where, when, and the recognition confidence.

Timeline Entry

{
  "id": "tl_abc123",
  "event_id": "evt_xyz",
  "attendee_id": "att_456",
  "attendee_name": "Jane Smith",
  "room_id": "room_lobby",
  "camera_id": "cam_entry1",
  "action": "entered",
  "confidence": 0.87,
  "timestamp": "2026-06-15T09:23:45Z",
  "face_crop_url": "https://storage.securegate.dev.satschel.com/crops/tl_abc123.jpg"
}

Field	Description
`action`	`entered` (from entry camera) or `exited` (from exit camera)
`confidence`	Cosine similarity score of the face match
`face_crop_url`	Link to the detected face crop (encrypted at rest, signed URL)

API

GET /timeline

Query presence logs for an event:

curl "https://api.securegate.dev.satschel.com/timeline?event_id=evt_xyz" \
  -H "Authorization: Bearer $TOKEN"

Response:

{
  "entries": [
    {
      "id": "tl_001",
      "attendee_id": "att_456",
      "attendee_name": "Jane Smith",
      "room_id": "room_lobby",
      "action": "entered",
      "confidence": 0.87,
      "timestamp": "2026-06-15T09:23:45Z"
    },
    {
      "id": "tl_002",
      "attendee_id": "att_456",
      "attendee_name": "Jane Smith",
      "room_id": "room_lobby",
      "action": "exited",
      "confidence": 0.84,
      "timestamp": "2026-06-15T09:45:12Z"
    }
  ],
  "aggregates": {
    "total_entries": 342,
    "total_exits": 298,
    "current_occupancy": 44,
    "unique_attendees_seen": 187,
    "peak_occupancy": 156,
    "peak_time": "2026-06-15T11:30:00Z"
  }
}

Filtering

Parameter	Type	Description
`event_id`	string	Required. Filter by event
`room_id`	string	Filter by specific room
`attendee_id`	string	Filter by specific attendee
`action`	string	Filter by `entered` or `exited`
`from`	ISO 8601	Start of time range
`to`	ISO 8601	End of time range

Occupancy Tracking

Room occupancy is derived from the timeline in real-time:

Current occupancy = count(entered) - count(exited)

The dashboard displays occupancy for each room with color-coded status:

Status	Condition	Display
Normal	Below 80% capacity	Green
Warning	80-100% capacity	Yellow
Over capacity	Above 100% capacity	Red

Aggregates

The timeline API returns pre-computed aggregates:

Aggregate	Description
`total_entries`	Total entry events across all rooms
`total_exits`	Total exit events across all rooms
`current_occupancy`	Current net occupancy (entries - exits)
`unique_attendees_seen`	Count of distinct attendees detected
`peak_occupancy`	Highest concurrent occupancy during event
`peak_time`	Timestamp of peak occupancy

Dwell Time

For individual attendees, dwell time per room is calculated from entry/exit pairs:

Dwell time = exit_timestamp - entry_timestamp

If an attendee has entered but not exited, the current dwell time is calculated from the entry timestamp to now. This is exposed in the per-attendee view on the operator dashboard.

Timeline entries are retained for the duration configured by the tenant's data retention policy. When the retention period expires, timeline entries and associated face crops are deleted. If the tenant is deleted entirely, the TEK is destroyed, making all encrypted data (including face crops in S3) unrecoverable (crypto-shredding).

Timeline