# Session Recording Search

Session Recording Search lets you find relevant session recordings by searching their summaries and session metadata. You can search with a natural language description, exact keywords, or filters such as user, role, resource, label, session kind, time range, and severity.

Session Recording Search searches session summaries, not raw recording data. A recording appears in search results only after Teleport has generated a successful [session recording summary](https://goteleport.com/docs/ver/19.x/identity-security/session-summaries.md) for that session.

## How it works

When a session summary is generated, Teleport indexes the summary and related session metadata in Identity Security. Teleport also generates vector embeddings for summary chunks using the configured `retrieval_model` resource. When a user runs a search, Teleport Auth Service embeds the search query, queries Identity Security for matching summaries, applies Teleport RBAC checks, and returns only the sessions the user is allowed to view.

The default search mode is hybrid search, which combines keyword search and vector similarity search. You can also run keyword-only or embeddings-only searches.

---

AI AND EMBEDDINGS

Session Recording Search sends session summary text and user search queries to the embeddings provider configured in the `retrieval_model` resource. Review the same data handling and provider considerations that apply to [Session Recording Summaries](https://goteleport.com/docs/ver/19.x/identity-security/session-summaries.md).

---

## Prerequisites

- A Teleport Enterprise cluster v18.8.0 or later with Identity Security enabled.

- [Session Recording Summaries](https://goteleport.com/docs/ver/19.x/identity-security/session-summaries.md) enabled and generating successful summaries.

- For self-hosted deployments, Access Graph v1.30.0 or later.

- For self-hosted deployments, a PostgreSQL v14 or later database for Access Graph where these extensions are available:

  - `pg_trgm`, required for keyword search.
  - `pgvector`, required for vector similarity search. Its PostgreSQL extension name is `vector`.

- Permission to read the session recordings you want to search. Search results are filtered with the same `session` RBAC rules used for session recordings and summaries.

- At least one SSH node, Kubernetes cluster, or PostgreSQL database connected to Teleport to generate session recordings.

Teleport Enterprise Cloud manages Access Graph and its backing database. For self-hosted clusters, follow the [Docker](https://goteleport.com/docs/ver/19.x/identity-security/access-graph/self-hosted.md) or [Helm](https://goteleport.com/docs/ver/19.x/identity-security/access-graph/self-hosted-helm.md) Access Graph deployment guide and run Access Graph v1.30.0 or later.

Access Graph enables and manages the required PostgreSQL extensions automatically; you do not need to run `CREATE EXTENSION` manually.

## Step 1/3. Configure the retrieval model

The `retrieval_model` resource is a cluster-wide singleton named `retrieval-model`. It tells Teleport which embeddings provider to use for Session Recording Search and which inference model to use to convert natural language search queries into API requests and generate prose from session summaries.

The preset `editor` role can manage `retrieval_model` resources. If you use a custom administration role, grant `read`, `list`, `create`, `update`, and `delete` on `retrieval_model`.

For example, create a `session-search-admin.yaml` file with the following content:

```
kind: role
metadata:
  name: session-search-admin
spec:
  allow:
    rules:
    - resources: [retrieval_model]
      verbs: [read, list, create, update, delete]
version: v7

```

Session Recording Search needs both an embeddings provider and an inference model. The embeddings provider converts session summaries and search queries into vectors for semantic matching. The `inference_model_name` field points to an existing `inference_model` resource that Teleport uses to convert natural language search queries into API requests and generate prose from session summaries. In most deployments, this can be the same inference model you already configured for Session Recording Summaries.

Choose the tab that matches the embeddings provider you want to use:

**OpenAI**

You can reuse an existing `inference_secret` that contains your OpenAI or OpenAI-compatible API key. The following example uses the `openai-key` secret from the Session Recording Summaries setup and the `shell-summary-model` inference model.

Session Recording Search supports the `text-embedding-3-large` and `text-embedding-3-small` OpenAI embedding models:

```
kind: retrieval_model
version: v1
metadata:
  name: retrieval-model
spec:
  openai:
    openai_model_id: text-embedding-3-large
    api_key_secret_ref: openai-key
  inference_model_name: shell-summary-model

```

**Amazon Bedrock**

The following example uses Amazon Titan Text Embeddings. Replace the region with a region available in your AWS account. Session Recording Search supports only the `amazon.titan-embed-text-v2:0` Bedrock embedding model.

```
kind: retrieval_model
version: v1
metadata:
  name: retrieval-model
spec:
  bedrock:
    region: us-east-1
    bedrock_model_id: amazon.titan-embed-text-v2:0
  inference_model_name: shell-summary-model

```

Save the configuration as `retrieval-model.yaml`, then apply it:

```
$ tctl create -f retrieval-model.yaml
```

For infrastructure-as-code workflows, see the [`teleport_retrieval_model` Terraform resource](https://goteleport.com/docs/ver/19.x/reference/infrastructure-as-code/terraform-provider/resources/retrieval_model.md) or the [`TeleportRetrievalModelV1` Kubernetes operator resource](https://goteleport.com/docs/ver/19.x/reference/infrastructure-as-code/operator-resources/resources-teleport-dev-retrievalmodelsv1.md).

## Step 2/3. Generate searchable summaries

Conduct a new SSH, Kubernetes, or database session that matches one of your session summary inference policies. After the session ends, wait for Teleport to generate its summary. New successful summaries are indexed for Session Recording Search.

Select a resource type for instructions on connecting to the resource with `tsh`:

**Servers**

Run the `tsh ssh` command to connect to a server, specifying the login to assume on the server you are connecting to. The following command connects to the server `mynode` as user `root`:

```
$ tsh ssh root@mynode
```

You can also connect to servers using the Teleport Web UI by navigating to the **Resources** tab and selecting an SSH server.

**Kubernetes clusters**

To access a Teleport-connected Kubernetes cluster, run the following command to update your kubeconfig with a certificate signed by Teleport. The following command logs in to the cluster mycluster:

```
$ tsh kube login mycluster
```

Once you have logged into the cluster, run `tsh kubectl` to execute `kubectl` commands. Teleport can allow or deny access to specific Kubernetes cluster resources. `tsh kubectl` detects whether the command has failed due to insufficient permissions and, if so, submits an Access Request for the target Kubernetes resource.

For example, the following creates an interactive session using the `sh` command in pod `my-pod`:

```
$ kubectl exec -it my-pod -- sh
```

You can also connect to Kubernetes resources using the Teleport Web UI by navigating to the **Resources** tab and selecting a Kubernetes cluster.

**PostgreSQL database**

To connect to a PostgreSQL database and generate a session recording, use the Teleport Web UI. Navigate to the **Resources** tab, select a PostgreSQL database, and start an interactive session.

## Step 3/3. Search recordings

Use `tctl recordings search` to search summarized recordings. By default, the command searches the last 24 hours and opens an interactive terminal UI.

```
$ tctl recordings search "SSH sessions downloading archives from production"
```

Search with filters:

```
$ tctl recordings search \
    --from=2026-05-01 \
    --to=2026-05-04 \
    --kind=ssh \
    --username=alice \
    --label=env=prod \
    --severity=high \
    "external endpoint"
```

Use JSON or YAML output for automation:

```
$ tctl recordings search --format=json --limit=25 "DROP TABLE"
```

Choose a search mode:

```
$ tctl recordings search --search-mode=keyword "rm -rf"
$ tctl recordings search --search-mode=embeddings "credential harvesting"
```

Supported search modes are:

| Mode         | Description                                                    |
| ------------ | -------------------------------------------------------------- |
| `hybrid`     | Default. Combines keyword search and vector similarity search. |
| `keyword`    | Uses keyword matching only.                                    |
| `embeddings` | Uses vector similarity search only.                            |

Common filters include:

| Flag               | Description                                                       |
| ------------------ | ----------------------------------------------------------------- |
| `--from`, `--to`   | Search time range in `YYYY-MM-DD` format.                         |
| `--kind`           | Session kind, such as `ssh`, `k8s`, or `db`. Can be repeated.     |
| `--username`       | Teleport user who initiated the session.                          |
| `--role`           | Role held by the user during the session. Can be repeated.        |
| `--access-request` | Access Request ID associated with the session. Can be repeated.   |
| `--resource-kind`  | Teleport resource kind, such as `node`, `kube_cluster`, or `db`.  |
| `--resource-name`  | Name of the accessed resource.                                    |
| `--label`          | Resource labels in `key=value` form.                              |
| `--severity`       | Minimum summary severity: `low`, `medium`, `high`, or `critical`. |

## Next steps

- [tctl recordings search reference](https://goteleport.com/docs/ver/19.x/reference/cli/tctl.md#tctl-recordings-search)

## Troubleshooting

### Session Recording Search requires Access Graph to be enabled with session recording support

Make sure your cluster is connected to Access Graph and that self-hosted deployments run Access Graph v1.30.0 or later.

### Check PostgreSQL extension availability

Connect to the PostgreSQL database used by Access Graph and query `pg_available_extensions`:

```
SELECT name, default_version, installed_version
FROM pg_available_extensions
WHERE name IN ('pg_trgm', 'vector')
ORDER BY name;

```

`pg_trgm` should appear as `pg_trgm`. `pgvector` should appear as `vector`, which is the PostgreSQL extension name. If a row is missing, that extension is not available in the PostgreSQL instance. If `installed_version` is empty, the extension is available but is not enabled in the current database yet; Access Graph enables required extensions automatically when it initializes the database.

### Session Recording Search requires the pg\_trgm PostgreSQL extension

Use a PostgreSQL instance where `pg_trgm` is available to the Access Graph database. Access Graph enables the extension automatically.

### Session Recording Search requires the pgvector PostgreSQL extension

Use a PostgreSQL instance where `pgvector` is available to the Access Graph database. Access Graph enables the `vector` extension automatically.

### No sessions found

Check that the search time range includes the session, that the session has a successful summary, and that your Teleport roles allow you to read the recording. Session Recording Search does not return recordings that have not been summarized.