Source activity
Report listening state and read recent source presence.
Source activity shows which of an account's sources are connected or listening right now, and how much of their audio is waiting for transcription.
Presence comes only from reports sent by apps and recorder firmware. It does not upload audio or prove that a recording was saved:
offlinemeans Optima has no current report. It does not prove the source stopped listening.- A connected source that never reports appears offline.
- Queued and transcribing counts come from confirmed audio and are independent of presence.
Report app activity
An app or integration reports for its own ios, macos, web, or api source with its bearer session:
curl -X POST https://api.getoptima.com/sources/SOURCE_ID/activity \
-H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
-H 'X-API-Version: 1' \
-H 'Content-Type: application/json' \
-d '{"listening":true}'The body is { "listening": true } while the source captures audio, or
{ "listening": false } when it is connected but idle. There are no session IDs
or platform-specific fields.
Reporting cycle
- One sender owns reporting for each source. Coordinate duplicate app instances locally.
- Report immediately when listening starts or stops.
- While connected, report about every 15 seconds, including when idle.
- Serialize requests and send the current state after reconnecting. Reports use server arrival order; do not replay queued historical heartbeats.
Each accepted report replaces the source's presence and renews a 60-second lease.
The response contains listening, last_seen_at, and expires_at. If a source
loses contact, its last report expires naturally. Client clocks do not control expiry.
App sessions cannot report for a recorder source; that returns 404. See report app activity.
Report recorder activity
A bound recorder calls POST /device/activity with its verified client certificate. The body has the listening state plus its current binding_epoch:
{
"listening": true,
"binding_epoch": "<binding_epoch>"
}Optima selects the device's account and source from its binding. A stale epoch returns 409. See Devices and report device activity.
Read source activity
GET /sources/activity returns one entry per account source in a { items, cursor } page. It uses the same limit and cursor parameters as GET /sources.
Each entry includes the source's id, kind, name, and created_at, plus:
| Field | Description |
|---|---|
status | listening, online, or offline |
last_seen_at | The most recent source report, or null |
online_expires_at, listening_expires_at | Expiry of the most recent report; listening expiry is null for idle sources |
last_received_at, last_captured_at | Server receipt time and capture end time of the latest received audio chunk, or null |
queued_chunks | Confirmed audio chunks waiting for transcription |
transcribing_chunks | Audio chunks being transcribed |
observed_at | The server time the entry was computed |
A source is listening when its current, unexpired report says so. It is online
when that report says it is idle, and offline after expiry. An upload of saved
audio does not change presence: recent receipt time is evidence of upload activity,
not proof that a microphone is currently listening.
See get source activity for the full schema.