# Search transcript

Search for words or phrases within a transcription and get matching segments with timestamps and confidence scores.

Searches for exact phrase matches within the transcription text. Returns all matching segments with their start and end timestamps (in seconds) and confidence scores. The search query supports 1 to 5 words with a maximum of 128 characters.

The transcription must be in `completed` or `processing` status for search to be available. If the transcription is still `queued`, a `409 Conflict` error is returned.

When word-level data is available locally, the search is performed server-side without an upstream API call, resulting in faster response times.

#### Path Parameters

**`transcription_id`** string required

The transcription ID with `trans_` prefix.

#### Query Parameters

**`query`** string required

The search query. Must be 1 to 128 characters and contain no more than 5 words.

## Returns

Returns a success envelope with:

- **`data.transcription_id`** -- The transcription ID.
- **`data.query`** -- The search query that was executed.
- **`data.matches`** -- Array of match objects, each containing:
  - `text` -- The matched text.
  - `start` -- Start time in seconds (3 decimal places).
  - `end` -- End time in seconds (3 decimal places).
  - `confidence` -- Confidence score (0.0 to 1.0).
- **`data.total_count`** -- Total number of matches found.
- **`metadata`** -- Request metadata: `request_id`, `timestamp`, `processing_time_ms`, `upstream_latency_ms`.


Request

```bash cURL
curl -s -X GET "https://api.aitronos.com/v1/audio/transcribe/trans_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6/search?query=quarterly%20results" \
  -H "Authorization: Bearer $ACCESS_TOKEN" | python3 -m json.tool
```


```python Python SDK
from aitronos import Aitronos

client = Aitronos(api_key="your-api-key")

result = client.audio.search_transcription(
    transcription_id="trans_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6",
    query="quarterly results",
)

print(f"Found {result.data.total_count} matches")
for match in result.data.matches:
    print(f"  [{match.start}s - {match.end}s] '{match.text}' (confidence: {match.confidence})")
```


```python Python
import requests

transcription_id = "trans_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6"
url = f"https://api.aitronos.com/v1/audio/transcribe/{transcription_id}/search"
headers = {"Authorization": "Bearer YOUR_ACCESS_TOKEN"}
params = {"query": "quarterly results"}

response = requests.get(url, headers=headers, params=params)
data = response.json()

for match in data["data"]["matches"]:
    print(f"[{match['start']}s - {match['end']}s] '{match['text']}'")
```


```javascript JavaScript
const accessToken = process.env.ACCESS_TOKEN;
const transcriptionId = 'trans_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6';

const params = new URLSearchParams({ query: 'quarterly results' });
const response = await fetch(
  `https://api.aitronos.com/v1/audio/transcribe/${transcriptionId}/search?${params}`,
  {
    headers: {
      'Authorization': `Bearer ${accessToken}`,
    },
  }
);

const data = await response.json();
console.log(`Found ${data.data.total_count} matches`);
data.data.matches.forEach(m => {
  console.log(`[${m.start}s - ${m.end}s] '${m.text}'`);
});
```

Response

```json 200 OK
{
  "success": true,
  "data": {
    "transcription_id": "trans_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6",
    "query": "quarterly results",
    "matches": [
      {
        "text": "quarterly results",
        "start": 8.456,
        "end": 9.890,
        "confidence": 0.97
      },
      {
        "text": "quarterly results",
        "start": 13.120,
        "end": 14.550,
        "confidence": 0.95
      }
    ],
    "total_count": 2
  },
  "metadata": {
    "request_id": "req_1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d",
    "timestamp": "2026-03-02T12:00:00Z",
    "processing_time_ms": 25,
    "upstream_latency_ms": 0
  }
}
```


```json 409 Conflict
{
  "success": false,
  "error": {
    "code": "TRANSCRIPTION_NOT_COMPLETE",
    "message": "This transcription is still being processed.",
    "system_message": "Transcription is not ready for search",
    "type": "client_error",
    "status": 409,
    "details": {
      "transcription_id": "trans_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6",
      "current_status": "queued",
      "reason": "search_not_ready"
    },
    "trace_id": "abc-123-def",
    "timestamp": "2026-03-02T12:00:00Z"
  }
}
```


```json 422 Validation Error
{
  "success": false,
  "error": {
    "code": "INVALID_PARAMETER",
    "message": "The provided parameter value is invalid.",
    "system_message": "Search query must not exceed 5 words",
    "type": "validation_error",
    "status": 422,
    "details": {
      "query": "this is a very long search query",
      "word_count": 7,
      "maximum": 5
    },
    "trace_id": "abc-123-def",
    "timestamp": "2026-03-02T12:00:00Z"
  }
}
```

## Related Resources

- [Create Transcription](/docs/api-reference/audio/create-transcription)
- [Get Transcription](/docs/api-reference/audio/get-transcription)
- [List Transcriptions](/docs/api-reference/audio/list-transcriptions)
- [Delete Transcription](/docs/api-reference/audio/delete-transcription)
- [Get Paragraphs](/docs/api-reference/audio/get-paragraphs)
- [Get Sentences](/docs/api-reference/audio/get-sentences)
- [Get Subtitles](/docs/api-reference/audio/get-subtitles)
- [Get Redacted Audio](/docs/api-reference/audio/get-redacted-audio)
- [Upload Audio File](/docs/api-reference/audio/upload-audio)