# search\_transcripts

Search transcripts by full text, archived agents included.

read-only · idempotent · MCP tool · [Agent](https://komrad.dev/latest/api/agent.md)

Quote phrases, prefix `-` to exclude, and narrow with qualifiers such as `from:me`, `agent:NAME`, `workflow:NAME`, `is:reviewer`, `since:2d` and `on:DATE`. Only the caller's transcript is searched unless [`agent_id`](https://komrad.dev/latest/api/agent/search-transcripts.md#komrad-agent-v1-SearchTranscriptsRequest-agent_id) or a qualifier names others.

## Calling it

```bash
curl -X POST http://127.0.0.1:8787/komrad.agent.v1.AgentService/SearchTranscripts \
  -H 'Content-Type: application/json' \
  -d '{
  "query": "<query>"
}'
```

```bash
komrad rpc search-transcripts \
  --query '<string>'
```

```json
{
  "name": "search_transcripts",
  "arguments": {
    "query": "<query>"
  }
}
```

Offered by the komrad MCP server to writer, reviewer, orchestrator agents.

## Request

### SearchTranscriptsRequest

| Field | Type | Description |
| --- | --- | --- |
| [`query`](https://komrad.dev/latest/api/agent/search-transcripts.md#komrad-agent-v1-SearchTranscriptsRequest-query) | string\* at most 500 characters | The words to search for, matched whole and stemmed. A quoted phrase matches in order, a leading minus excludes a word, and qualifiers narrow the search. |
| [`pagination`](https://komrad.dev/latest/api/agent/search-transcripts.md#komrad-agent-v1-SearchTranscriptsRequest-pagination) | [Pagination](https://komrad.dev/latest/api/agent/search-transcripts.md#komrad-pagination-v1-Pagination) | The page to read. One cursor pages through `matches` and `near` together. |
| [`agent_id`](https://komrad.dev/latest/api/agent/search-transcripts.md#komrad-agent-v1-SearchTranscriptsRequest-agent_id) | uuid | The agent whose transcript to search, by id. Unset searches the caller's own, unless a qualifier names other agents. |

## Response

### SearchTranscriptsResponse

| Field | Type | Description |
| --- | --- | --- |
| [`matches`](https://komrad.dev/latest/api/agent/search-transcripts.md#komrad-agent-v1-SearchTranscriptsResponse-matches) | [SearchHit\[\]](https://komrad.dev/latest/api/agent/search-transcripts.md#komrad-agent-v1-SearchHit) | The turns that contain the words, in the order the query asked for. |
| [`near`](https://komrad.dev/latest/api/agent/search-transcripts.md#komrad-agent-v1-SearchTranscriptsResponse-near) | [SearchHit\[\]](https://komrad.dev/latest/api/agent/search-transcripts.md#komrad-agent-v1-SearchHit) | The turns that contain the letters only inside other text, such as a word inside a path. They are ranked by how closely the letters match. |
| [`next_page_token`](https://komrad.dev/latest/api/agent/search-transcripts.md#komrad-agent-v1-SearchTranscriptsResponse-next_page_token) | string | The cursor for the next page of both lists. Unset on the last page. |

## Types

### Pagination

Pagination selects one page of a listing.

| Field | Type | Description |
| --- | --- | --- |
| [`limit`](https://komrad.dev/latest/api/agent/search-transcripts.md#komrad-pagination-v1-Pagination-limit) | int32 at least 0 | How many records to return. Komrad caps the value, and picks one when unset. |
| [`cursor`](https://komrad.dev/latest/api/agent/search-transcripts.md#komrad-pagination-v1-Pagination-cursor) | string at most 2048 characters | The `next_page_token` from the previous response. Unset to start from the first page. |

### SearchHit

SearchHit is one turn of a transcript that matched a search.

| Field | Type | Description |
| --- | --- | --- |
| [`agent_id`](https://komrad.dev/latest/api/agent/search-transcripts.md#komrad-agent-v1-SearchHit-agent_id) | uuid\* | The id of the agent whose transcript holds the turn. |
| [`snippet`](https://komrad.dev/latest/api/agent/search-transcripts.md#komrad-agent-v1-SearchHit-snippet) | string | The turn's text around the match, with the match marked. |
| [`name`](https://komrad.dev/latest/api/agent/search-transcripts.md#komrad-agent-v1-SearchHit-name) | string | The agent's name. |
| [`archived`](https://komrad.dev/latest/api/agent/search-transcripts.md#komrad-agent-v1-SearchHit-archived) | bool | Whether the agent is archived. Search includes archived agents. |
| [`score`](https://komrad.dev/latest/api/agent/search-transcripts.md#komrad-agent-v1-SearchHit-score) | double | How well the turn matched. Zero when the hits are ordered by time. |
| [`seq`](https://komrad.dev/latest/api/agent/search-transcripts.md#komrad-agent-v1-SearchHit-seq) | int32 | The turn's position in the transcript, counting from zero. |
| [`role`](https://komrad.dev/latest/api/agent/search-transcripts.md#komrad-agent-v1-SearchHit-role) | string | Who wrote the turn: the agent, or whoever prompted it. |
| [`content_offset`](https://komrad.dev/latest/api/agent/search-transcripts.md#komrad-agent-v1-SearchHit-content_offset) | int64 | The byte offset of the turn in the whole transcript, for reading the text around it. |
| [`content_length`](https://komrad.dev/latest/api/agent/search-transcripts.md#komrad-agent-v1-SearchHit-content_length) | int64 | How many bytes the turn runs to from [`content_offset`](https://komrad.dev/latest/api/agent/search-transcripts.md#komrad-agent-v1-SearchHit-content_offset). |
| [`spoken_at`](https://komrad.dev/latest/api/agent/search-transcripts.md#komrad-agent-v1-SearchHit-spoken_at) | timestamp | When the turn was written. Unset when the CLI's log was gone before komrad read the time. |
