Query Sessions

Search and filter through session data

POST /v1/session/query

cURL

cURL

curl --request POST \
  --url https://api.helicone.ai/v1/session/query \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "search": "<string>",
  "timeFilter": {
    "endTimeUnixMs": 123,
    "startTimeUnixMs": 123
  },
  "timezoneDifference": 123,
  "filter": {
    "request_response_rmt": {
      "country_code": {
        "not-equals": "<string>",
        "equals": "<string>",
        "like": "<string>",
        "ilike": "<string>",
        "contains": "<string>",
        "not-contains": "<string>"
      },
      "latency": {
        "not-equals": 123,
        "equals": 123,
        "gte": 123,
        "lte": 123,
        "lt": 123,
        "gt": 123
      },
      "cost": {
        "not-equals": 123,
        "equals": 123,
        "gte": 123,
        "lte": 123,
        "lt": 123,
        "gt": 123
      },
      "provider": {
        "not-equals": "<string>",
        "equals": "<string>",
        "like": "<string>",
        "ilike": "<string>",
        "contains": "<string>",
        "not-contains": "<string>"
      },
      "time_to_first_token": {
        "not-equals": 123,
        "equals": 123,
        "gte": 123,
        "lte": 123,
        "lt": 123,
        "gt": 123
      },
      "status": {
        "not-equals": 123,
        "equals": 123,
        "gte": 123,
        "lte": 123,
        "lt": 123,
        "gt": 123
      },
      "request_created_at": {
        "equals": "2023-11-07T05:31:56Z",
        "gte": "2023-11-07T05:31:56Z",
        "lte": "2023-11-07T05:31:56Z",
        "lt": "2023-11-07T05:31:56Z",
        "gt": "2023-11-07T05:31:56Z"
      },
      "response_created_at": {
        "equals": "2023-11-07T05:31:56Z",
        "gte": "2023-11-07T05:31:56Z",
        "lte": "2023-11-07T05:31:56Z",
        "lt": "2023-11-07T05:31:56Z",
        "gt": "2023-11-07T05:31:56Z"
      },
      "model": {
        "not-equals": "<string>",
        "equals": "<string>",
        "like": "<string>",
        "ilike": "<string>",
        "contains": "<string>",
        "not-contains": "<string>"
      },
      "user_id": {
        "not-equals": "<string>",
        "equals": "<string>",
        "like": "<string>",
        "ilike": "<string>",
        "contains": "<string>",
        "not-contains": "<string>"
      },
      "organization_id": {
        "not-equals": "<string>",
        "equals": "<string>",
        "like": "<string>",
        "ilike": "<string>",
        "contains": "<string>",
        "not-contains": "<string>"
      },
      "node_id": {
        "not-equals": "<string>",
        "equals": "<string>",
        "like": "<string>",
        "ilike": "<string>",
        "contains": "<string>",
        "not-contains": "<string>"
      },
      "job_id": {
        "not-equals": "<string>",
        "equals": "<string>",
        "like": "<string>",
        "ilike": "<string>",
        "contains": "<string>",
        "not-contains": "<string>"
      },
      "threat": {
        "equals": true
      },
      "request_id": {
        "not-equals": "<string>",
        "equals": "<string>",
        "like": "<string>",
        "ilike": "<string>",
        "contains": "<string>",
        "not-contains": "<string>"
      },
      "prompt_tokens": {
        "not-equals": 123,
        "equals": 123,
        "gte": 123,
        "lte": 123,
        "lt": 123,
        "gt": 123
      },
      "completion_tokens": {
        "not-equals": 123,
        "equals": 123,
        "gte": 123,
        "lte": 123,
        "lt": 123,
        "gt": 123
      },
      "prompt_cache_read_tokens": {
        "not-equals": 123,
        "equals": 123,
        "gte": 123,
        "lte": 123,
        "lt": 123,
        "gt": 123
      },
      "prompt_cache_write_tokens": {
        "not-equals": 123,
        "equals": 123,
        "gte": 123,
        "lte": 123,
        "lt": 123,
        "gt": 123
      },
      "total_tokens": {
        "not-equals": 123,
        "equals": 123,
        "gte": 123,
        "lte": 123,
        "lt": 123,
        "gt": 123
      },
      "target_url": {
        "not-equals": "<string>",
        "equals": "<string>",
        "like": "<string>",
        "ilike": "<string>",
        "contains": "<string>",
        "not-contains": "<string>"
      },
      "property_key": {
        "equals": "<string>"
      },
      "properties": {},
      "search_properties": {},
      "scores": {},
      "scores_column": {
        "not-equals": "<string>",
        "equals": "<string>",
        "like": "<string>",
        "ilike": "<string>",
        "contains": "<string>",
        "not-contains": "<string>"
      },
      "request_body": {
        "not-equals": "<string>",
        "equals": "<string>",
        "like": "<string>",
        "ilike": "<string>",
        "contains": "<string>",
        "not-contains": "<string>"
      },
      "response_body": {
        "not-equals": "<string>",
        "equals": "<string>",
        "like": "<string>",
        "ilike": "<string>",
        "contains": "<string>",
        "not-contains": "<string>"
      },
      "cache_enabled": {
        "equals": true
      },
      "cache_reference_id": {
        "not-equals": "<string>",
        "equals": "<string>",
        "like": "<string>",
        "ilike": "<string>",
        "contains": "<string>",
        "not-contains": "<string>"
      },
      "cached": {
        "equals": true
      },
      "assets": {
        "not-equals": "<string>",
        "equals": "<string>",
        "like": "<string>",
        "ilike": "<string>",
        "contains": "<string>",
        "not-contains": "<string>"
      },
      "helicone-score-feedback": {
        "equals": true
      },
      "prompt_id": {
        "not-equals": "<string>",
        "equals": "<string>",
        "like": "<string>",
        "ilike": "<string>",
        "contains": "<string>",
        "not-contains": "<string>"
      },
      "prompt_version": {
        "not-equals": "<string>",
        "equals": "<string>",
        "like": "<string>",
        "ilike": "<string>",
        "contains": "<string>",
        "not-contains": "<string>"
      },
      "request_referrer": {
        "not-equals": "<string>",
        "equals": "<string>",
        "like": "<string>",
        "ilike": "<string>",
        "contains": "<string>",
        "not-contains": "<string>"
      },
      "is_passthrough_billing": {
        "equals": true
      }
    },
    "sessions_request_response_rmt": {
      "session_session_id": {
        "not-equals": "<string>",
        "equals": "<string>",
        "like": "<string>",
        "ilike": "<string>",
        "contains": "<string>",
        "not-contains": "<string>"
      },
      "session_session_name": {
        "not-equals": "<string>",
        "equals": "<string>",
        "like": "<string>",
        "ilike": "<string>",
        "contains": "<string>",
        "not-contains": "<string>"
      },
      "session_total_cost": {
        "not-equals": 123,
        "equals": 123,
        "gte": 123,
        "lte": 123,
        "lt": 123,
        "gt": 123
      },
      "session_total_tokens": {
        "not-equals": 123,
        "equals": 123,
        "gte": 123,
        "lte": 123,
        "lt": 123,
        "gt": 123
      },
      "session_prompt_tokens": {
        "not-equals": 123,
        "equals": 123,
        "gte": 123,
        "lte": 123,
        "lt": 123,
        "gt": 123
      },
      "session_completion_tokens": {
        "not-equals": 123,
        "equals": 123,
        "gte": 123,
        "lte": 123,
        "lt": 123,
        "gt": 123
      },
      "session_total_requests": {
        "not-equals": 123,
        "equals": 123,
        "gte": 123,
        "lte": 123,
        "lt": 123,
        "gt": 123
      },
      "session_created_at": {
        "equals": "2023-11-07T05:31:56Z",
        "gte": "2023-11-07T05:31:56Z",
        "lte": "2023-11-07T05:31:56Z",
        "lt": "2023-11-07T05:31:56Z",
        "gt": "2023-11-07T05:31:56Z"
      },
      "session_latest_request_created_at": {
        "equals": "2023-11-07T05:31:56Z",
        "gte": "2023-11-07T05:31:56Z",
        "lte": "2023-11-07T05:31:56Z",
        "lt": "2023-11-07T05:31:56Z",
        "gt": "2023-11-07T05:31:56Z"
      },
      "session_tag": {
        "not-equals": "<string>",
        "equals": "<string>",
        "like": "<string>",
        "ilike": "<string>",
        "contains": "<string>",
        "not-contains": "<string>"
      }
    }
  },
  "nameEquals": "<string>",
  "offset": 123,
  "limit": 123
}
'

200

{
  "data": [
    {
      "created_at": "<string>",
      "latest_request_created_at": "<string>",
      "session_id": "<string>",
      "session_name": "<string>",
      "total_cost": 123,
      "total_requests": 123,
      "prompt_tokens": 123,
      "completion_tokens": 123,
      "total_tokens": 123,
      "avg_latency": 123,
      "user_ids": [
        "<string>"
      ]
    }
  ],
  "error": null
}

For users in the European Union: Please use eu.api.helicone.ai instead of api.helicone.ai.

Overview

The Session Query API allows you to search and filter sessions with advanced criteria including time ranges, session names, custom properties, and full-text search. This is essential for debugging AI agent workflows, analyzing conversation patterns, and building custom analytics.

Quick Start

Basic Query

Query all sessions within a time range:

curl --request POST \
  --url https://api.helicone.ai/v1/session/query \
  --header "Content-Type: application/json" \
  --header "authorization: Bearer $HELICONE_API_KEY" \
  --data '{
  "startTimeUnixMs": 1704067200000,
  "endTimeUnixMs": 1704153600000,
  "timezoneDifference": 0,
  "limit": 100
}'

Required Parameters:

• startTimeUnixMs - Start of time range (Unix timestamp in milliseconds)
• endTimeUnixMs - End of time range (Unix timestamp in milliseconds)
• timezoneDifference - Timezone offset in hours (e.g., -5 for EST, 0 for UTC)

Filter Examples

Filter by Session Name

Find all sessions with a specific name:

curl --request POST \
  --url https://api.helicone.ai/v1/session/query \
  --header "Content-Type: application/json" \
  --header "authorization: Bearer $HELICONE_API_KEY" \
  --data '{
  "startTimeUnixMs": 1704067200000,
  "endTimeUnixMs": 1704153600000,
  "timezoneDifference": 0,
  "nameEquals": "Customer Support",
  "limit": 100
}'

Search Sessions

Search across session names and metadata:

curl --request POST \
  --url https://api.helicone.ai/v1/session/query \
  --header "Content-Type: application/json" \
  --header "authorization: Bearer $HELICONE_API_KEY" \
  --data '{
  "startTimeUnixMs": 1704067200000,
  "endTimeUnixMs": 1704153600000,
  "timezoneDifference": 0,
  "search": "authentication error",
  "limit": 100
}'

Filter by Custom Properties

Important: When filtering by custom properties, wrap the properties filter inside a session object. Each property condition must be a separate leaf node.

Single property filter:

curl --request POST \
  --url https://api.helicone.ai/v1/session/query \
  --header "Content-Type: application/json" \
  --header "authorization: Bearer $HELICONE_API_KEY" \
  --data '{
  "startTimeUnixMs": 1704067200000,
  "endTimeUnixMs": 1704153600000,
  "timezoneDifference": 0,
  "filter": {
    "session": {
      "properties": {
        "environment": {
          "equals": "production"
        }
      }
    }
  },
  "limit": 100
}'

Multiple property filters (AND):

curl --request POST \
  --url https://api.helicone.ai/v1/session/query \
  --header "Content-Type: application/json" \
  --header "authorization: Bearer $HELICONE_API_KEY" \
  --data '{
  "startTimeUnixMs": 1704067200000,
  "endTimeUnixMs": 1704153600000,
  "timezoneDifference": 0,
  "filter": {
    "left": {
      "session": {
        "properties": {
          "product": {
            "equals": "ai-writer"
          }
        }
      }
    },
    "operator": "and",
    "right": {
      "session": {
        "properties": {
          "source": {
            "equals": "slack"
          }
        }
      }
    }
  },
  "limit": 100
}'

Multiple property filters (OR):

curl --request POST \
  --url https://api.helicone.ai/v1/session/query \
  --header "Content-Type: application/json" \
  --header "authorization: Bearer $HELICONE_API_KEY" \
  --data '{
  "startTimeUnixMs": 1704067200000,
  "endTimeUnixMs": 1704153600000,
  "timezoneDifference": 0,
  "filter": {
    "left": {
      "session": {
        "properties": {
          "priority": {
            "equals": "high"
          }
        }
      }
    },
    "operator": "or",
    "right": {
      "session": {
        "properties": {
          "priority": {
            "equals": "critical"
          }
        }
      }
    }
  },
  "limit": 100
}'

Combine Name and Properties

Query sessions by name AND custom properties:

curl --request POST \
  --url https://api.helicone.ai/v1/session/query \
  --header "Content-Type: application/json" \
  --header "authorization: Bearer $HELICONE_API_KEY" \
  --data '{
  "startTimeUnixMs": 1704067200000,
  "endTimeUnixMs": 1704153600000,
  "timezoneDifference": 0,
  "nameEquals": "Code Generation Assistant",
  "filter": {
    "session": {
      "properties": {
        "environment": {
          "equals": "production"
        }
      }
    }
  },
  "limit": 100
}'

Common Use Cases

Debug User Sessions in Last 24 Hours

Find all sessions from a specific user in the last day:

# Calculate timestamps (Unix time in milliseconds)
END_TIME=$(date +%s)000
START_TIME=$((END_TIME - 86400000))  # 24 hours ago

curl --request POST \
  --url https://api.helicone.ai/v1/session/query \
  --header "Content-Type: application/json" \
  --header "authorization: Bearer $HELICONE_API_KEY" \
  --data "{
  \"startTimeUnixMs\": $START_TIME,
  \"endTimeUnixMs\": $END_TIME,
  \"timezoneDifference\": 0,
  \"filter\": {
    \"session\": {
      \"properties\": {
        \"user-id\": {
          \"equals\": \"user-123\"
        }
      }
    }
  },
  \"limit\": 100
}"

Find Failed Sessions

Query sessions with error status:

curl --request POST \
  --url https://api.helicone.ai/v1/session/query \
  --header "Content-Type: application/json" \
  --header "authorization: Bearer $HELICONE_API_KEY" \
  --data '{
  "startTimeUnixMs": 1704067200000,
  "endTimeUnixMs": 1704153600000,
  "timezoneDifference": 0,
  "filter": {
    "session": {
      "properties": {
        "status": {
          "equals": "error"
        }
      }
    }
  },
  "limit": 100
}'

Production Sessions by Version

Filter by environment and version:

curl --request POST \
  --url https://api.helicone.ai/v1/session/query \
  --header "Content-Type: application/json" \
  --header "authorization: Bearer $HELICONE_API_KEY" \
  --data '{
  "startTimeUnixMs": 1704067200000,
  "endTimeUnixMs": 1704153600000,
  "timezoneDifference": 0,
  "filter": {
    "left": {
      "session": {
        "properties": {
          "environment": {
            "equals": "production"
          }
        }
      }
    },
    "operator": "and",
    "right": {
      "session": {
        "properties": {
          "version": {
            "equals": "v2.1.0"
          }
        }
      }
    }
  },
  "limit": 100
}'

Complex Multi-Property Filter

Combine multiple conditions with AND/OR logic:

curl --request POST \
  --url https://api.helicone.ai/v1/session/query \
  --header "Content-Type: application/json" \
  --header "authorization: Bearer $HELICONE_API_KEY" \
  --data '{
  "startTimeUnixMs": 1704067200000,
  "endTimeUnixMs": 1704153600000,
  "timezoneDifference": 0,
  "filter": {
    "left": {
      "left": {
        "session": {
          "properties": {
            "product": {
              "equals": "ai-writer"
            }
          }
        }
      },
      "operator": "and",
      "right": {
        "session": {
          "properties": {
            "source": {
              "equals": "slack"
            }
          }
        }
      }
    },
    "operator": "and",
    "right": {
      "session": {
        "properties": {
          "environment": {
            "equals": "production"
          }
        }
      }
    }
  },
  "limit": 100
}'

Pagination

Use offset and limit to paginate through large result sets:

# First page (0-99)
curl --request POST \
  --url https://api.helicone.ai/v1/session/query \
  --header "Content-Type: application/json" \
  --header "authorization: Bearer $HELICONE_API_KEY" \
  --data '{
  "startTimeUnixMs": 1704067200000,
  "endTimeUnixMs": 1704153600000,
  "timezoneDifference": 0,
  "offset": 0,
  "limit": 100
}'

# Second page (100-199)
curl --request POST \
  --url https://api.helicone.ai/v1/session/query \
  --header "Content-Type: application/json" \
  --header "authorization: Bearer $HELICONE_API_KEY" \
  --data '{
  "startTimeUnixMs": 1704067200000,
  "endTimeUnixMs": 1704153600000,
  "timezoneDifference": 0,
  "offset": 100,
  "limit": 100
}'

Filter Structure

The filter parameter uses an AST (Abstract Syntax Tree) structure where each condition is a separate leaf node:

Filter Leaf (Single Condition)

{
  "session": {
    "properties": {
      "property-name": {
        "equals": "value"
      }
    }
  }
}

Filter Branch (Multiple Conditions)

{
  "left": FilterNode,
  "operator": "and" | "or",
  "right": FilterNode
}

Available Operators

For property values:

• equals - Exact match
• not-equals - Not equal to
• contains - Contains substring
• not-contains - Does not contain substring

Response Format

The API returns an array of session objects with the following structure:

{
  "data": [
    {
      "session_id": "550e8400-e29b-41d4-a716-446655440000",
      "session_name": "Customer Support",
      "created_at": "2024-01-01T12:00:00Z",
      "last_used": "2024-01-01T12:30:00Z",
      "total_requests": 15,
      "total_cost": 0.0234,
      "properties": {
        "user-id": "user-123",
        "environment": "production"
      }
    }
  ],
  "error": null
}

Troubleshooting

Empty Results

If you’re getting empty results when you know sessions exist:

1. Check time range - Ensure your timestamps are in milliseconds and cover the correct period:

# Get current time in milliseconds
date +%s000

# Convert specific date to milliseconds (macOS/Linux)
date -d "2024-01-01" +%s000

2. Verify property names - Property names are case-sensitive and must match exactly:

# ❌ Wrong - case mismatch
"properties": {
  "Environment": { "equals": "production" }
}

# ✅ Correct - exact match
"properties": {
  "environment": { "equals": "production" }
}

3. Check filter structure - Each property condition must be wrapped in a session object:

❌ WRONG - Missing session wrapper

{
  "filter": {
    "properties": {
      "environment": {
        "equals": "production"
      }
    }
  }
}

✅ CORRECT - With session wrapper

{
  "filter": {
    "session": {
      "properties": {
        "environment": {
          "equals": "production"
        }
      }
    }
  }
}

Region Issues

Make sure you’re using the correct regional endpoint:

• US: https://api.helicone.ai/v1/session/query
• EU: https://eu.api.helicone.ai/v1/session/query

Related Resources

Sessions Overview

Learn how to create and structure sessions

Custom Properties

Add metadata to sessions for advanced filtering

Request Query API

Query individual requests within sessions

Getting Sessions Guide

Step-by-step guide to retrieving session data

Authorizations

Authorization · string · header · required

Bearer token authentication. Format: 'Bearer YOUR_API_KEY'

Body

application/json

search · string · required

timeFilter · object · required

Show child attributes

timezoneDifference · number<double> · required

filter · Option 1 · object Option 2 · object Option 3 · enum<string> · required

From T, pick a set of properties whose keys are in the union K

Show child attributes

nameEquals · string

offset · number<double>

limit · number<double>

Response

200 - application/json

Ok

Option 1

Option 2

data · object[] · required

Show child attributes

error · enum<number> | null · required

Available options: null