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

# Search Sessions

> Search for sessions by matching content in session data, including variables and messages.

<Warning>
  **Deprecated.** This endpoint is deprecated and will be **sunset on 2026-07-11**. It still works until then. Migrate to the V1 path -- see the [migration guide](/en/migrations/2026-06-outbound-api-v1) for the old -> new path table.
</Warning>

Search across all sessions to find matches based on string content in session data.

## Base URL

```
https://api.pathors.com
```

## Search Sessions

```bash theme={null}
POST https://api.pathors.com/project/{projectId}/session/search
```

### Path Parameters

<ParamField path="projectId" type="string" required>
  The ID of your project
</ParamField>

### Request Headers

<ParamField header="Authorization" type="string" required>
  Bearer token authentication using your Project API Key (starts with `sk_`). Format: `Bearer {your-api-key}`
</ParamField>

### Request Body

<ParamField body="search_string" type="string" required>
  The string to search for in session data. This will match against all session content including variables, messages, and other stored information.
</ParamField>

<ParamField body="limit" type="number">
  Maximum number of results to return. Default: 50
</ParamField>

<ParamField body="offset" type="number">
  Number of results to skip for pagination. Default: 0
</ParamField>

### Response

<ResponseField name="results" type="array">
  Array of matching sessions, ordered by most recently updated first

  <Expandable title="Session Object">
    <ResponseField name="sessionId" type="string">
      The session ID
    </ResponseField>

    <ResponseField name="data" type="object">
      The session data containing variables, messages, and other session information
    </ResponseField>

    <ResponseField name="createdAt" type="string">
      ISO 8601 timestamp when the session was created
    </ResponseField>

    <ResponseField name="updatedAt" type="string">
      ISO 8601 timestamp when the session was last updated
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="pagination" type="object">
  Pagination information

  <Expandable title="Pagination Object">
    <ResponseField name="limit" type="number">
      The limit used for this request
    </ResponseField>

    <ResponseField name="offset" type="number">
      The offset used for this request
    </ResponseField>

    <ResponseField name="total" type="number">
      Total number of matching sessions
    </ResponseField>
  </Expandable>
</ResponseField>

## Example

### Request

```bash theme={null}
curl -X POST https://api.pathors.com/project/{projectId}/session/search \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "search_string": "John Doe",
    "limit": 10,
    "offset": 0
  }'
```

### Response

```json theme={null}
{
  "results": [
    {
      "sessionId": "user-123-session-456",
      "data": {
        "variables": {
          "userName": "John Doe",
          "userRole": "admin"
        },
        "messages": [
          {
            "role": "user",
            "content": "Hello"
          },
          {
            "role": "assistant",
            "content": "Hi John Doe! How can I help you today?"
          }
        ]
      },
      "createdAt": "2024-01-15T10:30:00.000Z",
      "updatedAt": "2024-01-15T10:35:00.000Z"
    },
    {
      "sessionId": "user-456-session-789",
      "data": {
        "variables": {
          "userName": "John Doe",
          "userRole": "user"
        },
        "messages": []
      },
      "createdAt": "2024-01-14T15:20:00.000Z",
      "updatedAt": "2024-01-14T15:25:00.000Z"
    }
  ],
  "pagination": {
    "limit": 10,
    "offset": 0,
    "total": 2
  }
}
```

## Usage Notes

* **Search String**: The search is case-sensitive and matches against the entire JSON content of the session data
* **Ordering**: Results are ordered by `updatedAt` in descending order (most recent first)
* **Pagination**: Use `limit` and `offset` to paginate through large result sets
* **Performance**: For large datasets, consider using more specific search strings to improve query performance

## Error Responses

| Status Code | Description                       |
| ----------- | --------------------------------- |
| 400         | Missing or invalid search\_string |
| 401         | Invalid authentication            |
| 500         | Internal server error             |

Example error responses:

**400 Bad Request:**

```json theme={null}
{
  "error": "search_string is required"
}
```

**401 Unauthorized:**

```json theme={null}
{
  "error": {
    "message": "Invalid authentication"
  }
}
```

## Related APIs

* [Create Session](/api-reference/session/create-session) - Create a new session
* [Query Session](/api-reference/session/query-session) - Get a specific session by ID
* [End Session](/api-reference/session/end-session) - End an existing session