> ## Documentation Index
> Fetch the complete documentation index at: https://docs.murmur.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# murmur session search

> Search your tenant's persisted agent turns by keyword or meaning and list the matching turns with excerpts.

Searches the persisted turns of your tenant's [agents](/concepts/agents) and lists the matches, ranked. Results only include agents you are allowed to see.

The command is for people, not agents: agent runtimes cannot call the search.

## Synopsis

```bash theme={null}
murmur session search [--limit N] [--owner provider/account] [--workspace name] <query>
```

Every word after the flags forms the query, so quoting is optional.

## Arguments

| Name | Type | Required | Description |
| - | - | - | - |
| `query` | string | yes | Plain-text keyword or semantic query. |
| `--limit` | int | no | Maximum matching turns. Server default 20, maximum 100. |
| `--owner` | string | no | Only agents owned by this identity, in `provider/account` form (for example `github_oauth/alice`). |
| `--workspace` | string | no | Only agents in this workspace. Unlike most commands, this flag filters the search: it does not select the workspace from `murmur.yaml`. |

## Output

A table with one row per matching turn:

| Column | Meaning |
| - | - |
| `AGENT` | The agent's full identifier. |
| `SPAWN ID` | The ID of the execution the turn belongs to. |
| `RUN ID` | The turn's run number within that execution. |
| `MATCHED` | When the matched turn completed, as `YYYY-MM-DDTHH:MM:SSZ`. |
| `EXCERPT` | The matching text. Control characters are replaced with spaces. |

## Examples

### Search every agent you can see

```bash theme={null}
murmur session search JWT expiry
```

```
AGENT                                                    SPAWN ID                              RUN ID  MATCHED               EXCERPT
github_app/acme/w/backend/github_oauth/alice/fix-auth  3f6c2a9e-8b1d-4e57-a0c4-91d2e7b5f308  3       2026-09-27T14:10:03Z  validate JWT expiry before checking claims
```

### Narrow to one owner and workspace

```bash theme={null}
murmur session search --owner github_oauth/alice --workspace backend --limit 5 flaky test
```

## Errors

| Code | Meaning | What to do |
| - | - | - |
| none | `usage: murmur session search ...` | Pass a query. |
| none | `--limit must be between 1 and 100` | Pass a limit from 1 to 100, or omit it. |
| `PERMISSION_DENIED` | You lack `tenant.read` on the tenant, or you are calling from an agent runtime (`session search is unavailable to agent-runtime callers`). | Run the search as yourself from your laptop. |
| `UNAUTHENTICATED` | Identity token is missing or expired. | Run [`murmur login`](/cli/login). |

## Related

* [`murmur session download`](/cli/session-download): download an agent's session transcript
* [`murmur session watch`](/cli/session-watch): stream an agent's session output
* [`murmur turns`](/cli/turns): list an agent's turns
* [`murmur history`](/cli/history): list past agent runs