Returns authorized acoustic measurements within the project contract period, with optional short-lived audio access.
| Time | Status | User Agent | |
|---|---|---|---|
Retrieving recent requests… | |||
Samples are normally sent every five minutes; gaps can occur because of power, connectivity, or invalid/corrupted samples.
Required authorization
The key must include v0:data: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 cursor is null or fewer than limit authorized records are returned.
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: truewith the actualmeta.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 sample may include the acoustic metrics, classification, the recalculated applicable limit, limitSource, and limitRecalculatedAt. Use datetime, the record id, and the response cursor for navigation.
The current schedule is used to recalculate the applicable limit and event status. These values may therefore 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 record 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 sample.flac
Do not persist or share audioUrl. If it expires, repeat the original Data 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.