Skip to main content
POST
/
recordings
/
search
curl -X POST https://api.bota.dev/v1/recordings/search \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "end_user_id": "eu_abc123",
    "query": "what did we agree on the budget?",
    "limit": 8
  }'

{
  "results": [
    {
      "chunk_id": "chk_abc123",
      "recording_id": "rec_def456",
      "transcription_id": "txn_ghi789",
      "chunk_text": "Let's lock the Q3 budget at 1.2M and revisit in August.",
      "speaker": "SPEAKER_0",
      "start_ms": 754000,
      "end_ms": 761200,
      "recorded_at": "2026-05-16T09:12:00Z",
      "score": 0.0312
    }
  ]
}
Run a hybrid (semantic + keyword) search across an end user’s transcripts and get back the most relevant excerpts. Each result carries start_ms/end_ms so you can deep-link a citation back to the moment in the audio. This is the retrieval primitive behind cross-recording AI Ask.

​
Authentication

Requires an API key with recordings:read scope. 
curl -X POST https://api.bota.dev/v1/recordings/search \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "end_user_id": "eu_abc123",
    "query": "what did we agree on the budget?",
    "limit": 8
  }'

​
Request Body

​
query
string
required
Natural-language search query (1–1000 characters).
​
end_user_id
string
End user whose recordings to search (eu_*). Required unless the API key is itself scoped to an end user.
​
recording_ids
string[]
Restrict the search to these recordings. Omit to search all of the end user’s recordings.
​
recorded_after
string
Only include chunks from recordings on or after this time (ISO 8601).
​
recorded_before
string
Only include chunks from recordings before this time (ISO 8601).
​
limit
integer
default:"8"
Maximum number of chunks to return (1–50).

​
Response

Returns the top-K most relevant transcript chunks, best first. 
{
  "results": [
    {
      "chunk_id": "chk_abc123",
      "recording_id": "rec_def456",
      "transcription_id": "txn_ghi789",
      "chunk_text": "Let's lock the Q3 budget at 1.2M and revisit in August.",
      "speaker": "SPEAKER_0",
      "start_ms": 754000,
      "end_ms": 761200,
      "recorded_at": "2026-05-16T09:12:00Z",
      "score": 0.0312
    }
  ]
}

​
Response Fields

FieldTypeDescription
chunk_idstringChunk identifier (chk_*)
recording_idstringRecording the chunk belongs to (rec_*)
transcription_idstringSource transcription (txn_*)
chunk_textstringThe excerpt text
speakerstring | nullDominant speaker label, or null if mixed/unknown
start_msintegerChunk start offset in the audio (milliseconds) — use for citation deep-links
end_msintegerChunk end offset (milliseconds)
recorded_atstring | nullWhen the recording was captured (ISO 8601)
scorenumberRelevance score (higher is more relevant)
Search only covers recordings that have a completed transcription — chunking + embedding runs automatically after transcription completes.