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

# Query Sessions

> Search and filter through session data with advanced filtering options

## Overview

The Query Sessions endpoint allows you to retrieve session data with powerful filtering capabilities. Sessions group related requests together, enabling you to track conversations, multi-step workflows, or any sequence of API calls.

## Request Parameters

<ParamField body="search" type="string">
  Search term to filter sessions by session ID or session name (case-insensitive)
</ParamField>

<ParamField body="timeFilter" type="object" required>
  Time range filter for the query

  <ParamField body="startTimeUnixMs" type="number" required>
    Start time in Unix milliseconds
  </ParamField>

  <ParamField body="endTimeUnixMs" type="number" required>
    End time in Unix milliseconds
  </ParamField>
</ParamField>

<ParamField body="nameEquals" type="string">
  Filter sessions by exact session name match
</ParamField>

<ParamField body="timezoneDifference" type="number" required>
  Timezone offset in minutes from UTC
</ParamField>

<ParamField body="filter" type="object" required>
  Advanced filter node for complex queries. Can be a filter leaf, filter branch, or "all" to match all sessions.
</ParamField>

<ParamField body="offset" type="number" default="0">
  Number of sessions to skip for pagination
</ParamField>

<ParamField body="limit" type="number" default="50">
  Maximum number of sessions to return (max: 1000)
</ParamField>

## Response Fields

<ResponseField name="data" type="array">
  Array of session objects

  <ResponseField name="session_id" type="string">
    Unique identifier for the session
  </ResponseField>

  <ResponseField name="session_name" type="string">
    Human-readable name for the session
  </ResponseField>

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

  <ResponseField name="latest_request_created_at" type="string">
    ISO 8601 timestamp of the most recent request in this session
  </ResponseField>

  <ResponseField name="total_cost" type="number">
    Total cost of all requests in the session (in USD)
  </ResponseField>

  <ResponseField name="total_requests" type="number">
    Number of requests in the session
  </ResponseField>

  <ResponseField name="prompt_tokens" type="number">
    Total prompt tokens used across all requests
  </ResponseField>

  <ResponseField name="completion_tokens" type="number">
    Total completion tokens generated across all requests
  </ResponseField>

  <ResponseField name="total_tokens" type="number">
    Sum of prompt and completion tokens
  </ResponseField>

  <ResponseField name="avg_latency" type="number">
    Average latency across all requests in milliseconds
  </ResponseField>

  <ResponseField name="user_ids" type="array">
    Array of unique user IDs associated with this session
  </ResponseField>
</ResponseField>

## Example Request

```bash theme={null}
curl -X POST https://api.helicone.ai/v1/session/query \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "search": "customer-support",
    "timeFilter": {
      "startTimeUnixMs": 1704067200000,
      "endTimeUnixMs": 1704153600000
    },
    "timezoneDifference": 0,
    "filter": "all",
    "offset": 0,
    "limit": 50
  }'
```

## Example Response

```json theme={null}
{
  "data": [
    {
      "session_id": "sess_abc123",
      "session_name": "customer-support-chat",
      "created_at": "2024-01-01T12:00:00Z",
      "latest_request_created_at": "2024-01-01T12:15:00Z",
      "total_cost": 0.0042,
      "total_requests": 8,
      "prompt_tokens": 1250,
      "completion_tokens": 890,
      "total_tokens": 2140,
      "avg_latency": 450.5,
      "user_ids": ["user_123"]
    }
  ],
  "error": null
}
```

## Filtering Sessions

You can use the `filter` parameter to create complex queries:

### Filter by session properties

```json theme={null}
{
  "filter": {
    "request_response_rmt": {
      "properties": {
        "Helicone-Session-Name": {
          "equals": "production-chat"
        }
      }
    }
  }
}
```

### Combine multiple filters

```json theme={null}
{
  "filter": {
    "left": {
      "request_response_rmt": {
        "properties": {
          "Helicone-Session-Name": {
            "contains": "support"
          }
        }
      }
    },
    "operator": "and",
    "right": {
      "request_response_rmt": {
        "cost": {
          "gt": 0.001
        }
      }
    }
  }
}
```

## Use Cases

* **Track conversations**: Monitor multi-turn chat sessions
* **Analyze workflows**: Group related API calls together
* **Cost monitoring**: Track spending per session
* **Performance analysis**: Measure session duration and latency
* **User analytics**: Understand user behavior across sessions