An event is an acoustic sample whose recalculated equivalent sound level exceeds the applicable current limit. Classification is produced by the configured model when available.

Required authorization

The key must include v0:events:read. The project and sensor must both be included in the key's allowed resources.

If withAudio=true, the key must additionally include v0:audio:read. Missing operation scopes return 403 Forbidden.

Use project and sensor IDs available to your API key. Unknown or unauthorized IDs return 404 Not found.

Query and pagination

startAt and endAt are required ISO 8601 values. limit is optional, defaults to 288, and accepts values from 1 to 2000. orderBy accepts asc or desc; fweighting accepts A, C, or Z.

Start without cursor or use cursor=0. When the response contains a non-null cursor, pass that exact Unix timestamp in seconds to the next request. Stop when the cursor is null.

A page may contain fewer events than the requested limit.

A cursor outside the effective contract range returns 400 Invalid request.

Contract period

The requested range is restricted to the project's contract period:

• a range fully inside the contract is used unchanged;
• a partially overlapping range is clamped and returns meta.clamped: true with the actual meta.effectiveRange;
• a fully non-overlapping range returns data: [], cursor: null, and a null effective range without querying telemetry;
• invalid or unavailable contract configuration returns 503 Service unavailable.

Contract boundaries are inclusive. Pagination and cursors never expand the effective range.

Response metadata

The response has the shape { data, cursor, meta }.

Each event includes its id, sensorId, datetime, classification, Leq, applicable limit, over, limitSource, limitRecalculatedAt, and fweighting.

over is the difference between Leq and the current applicable limit, rounded to two decimal places. Because the current schedule is used, the limit and event classification may differ from values persisted when the sample was originally collected.

Short-lived audio

Set withAudio=true to request audio access. When audio exists and can be authorized, the event includes a relative audioUrl and an ISO 8601 audioExpiresAt.

The URL normally expires after 10 minutes. Fetch it from the same OTOH host using the same API key:

curl --request GET \
  --url "https://www.otoh.com.br${audioUrl}" \
  --header 'otoh-api-key: Bearer YOUR_API_KEY' \
  --output event.flac

Do not persist or share audioUrl. If it expires, repeat the original Events request.

If no audio is attached or a lease cannot be issued for a record, audioUrl and audioExpiresAt are null. When withAudio=false, these fields are omitted.

All JSON and audio responses are private and non-cacheable. Only GET is accepted.