---
title: "Record a foreground usage-session event"
method: POST
path: "/api/analytics/usage-sessions/events"
tags: ["analytics"]
---

# Record a foreground usage-session event

`POST /api/analytics/usage-sessions/events`

## Request body

- UsageSessionEventRequest
  - `event_id` string, uuid, required — Client-generated idempotency UUID for this event
  - `session_id` string, uuid, required — UUID shared by start, heartbeat and end
  - `event_type` 'start' | 'heartbeat' | 'end', required
  - `occurred_at` string, date-time, required — Timezone-aware client timestamp
  - `channel` 'native_app' | 'web' — Delivery channel used for an app-open event.
  - `platform` 'ios' | 'android' | 'web' — Runtime platform used for an app-open event.
  - `form_factor` 'mobile' | 'tablet' | 'desktop' — Physical device class used for an app-open event.
  - `app_version` string, nullable
  - `device_id` string, uuid, nullable — Required on start; reuse the native chat device UUID

## Response `200`

Successful Response

- UsageSessionEventResponse
  - `event_id` string, uuid, required
  - `session_id` string, uuid, required
  - `event_type` 'start' | 'heartbeat' | 'end', required
  - `recorded_at` string, date-time, required
  - `foreground_seconds` integer, required
  - `status` 'active' | 'ended', required
  - `created` boolean, required — False when event_id was already processed

## Other responses

- `422` — Validation Error

---

[API](https://skmtc.dev/corabea/apis/corabea-api.md) · [All operations](https://skmtc.dev/corabea/apis/corabea-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/corabea/corabea-api/revisions/d6ed0fec5d4f/schema)