Skip to main content

​
Overview

Query requests from your Helicone organization with powerful filtering, sorting, and pagination capabilities. This endpoint allows you to retrieve requests based on various criteria including properties, feedback, timestamps, and more.

​
Endpoint

​
method
string
required
POST
​
url
string
required
/v1/request/query

​
Authentication

Requires API key authentication via the Authorization header: 
Authorization: Bearer YOUR_API_KEY

​
Request Body

​
filter
object
required
Filter criteria for requests. Supports nested filtering with AND/OR operators.The filter can be:
  • "all" - returns all requests
  • A filter object with specific criteria
  • A filter branch with left, operator (“and” | “or”), and right properties
Supported filter fields:
  • request - Filter by request properties (id, created_at, user_id, path, etc.)
  • response - Filter by response properties (status, model, etc.)
  • properties - Filter by custom properties
  • feedback - Filter by feedback ratings
  • values - Filter by request/response values
​
offset
number
default:"0"
Number of records to skip for pagination
​
limit
number
default:"10"
Maximum number of records to return (max: 100)
​
sort
object
Sort order for results. Example: { "created_at": "desc" }Supported sort fields:
  • created_at - Sort by request creation time
  • latency - Sort by request latency
  • cost - Sort by request cost
  • tokens - Sort by token usage
​
isCached
boolean
default:"false"
Filter for cached requests only
​
includeInputs
boolean
default:"false"
Include prompt inputs in the response
​
isPartOfExperiment
boolean
default:"false"
Filter for requests that are part of experiments
​
isScored
boolean
default:"false"
Filter for requests that have evaluation scores

​
Response

Returns an array of request objects matching the filter criteria.
​
data
array
Array of request objects
​
error
string
Error message if the request failed

​
Examples

​
Basic Query

Retrieve the 10 most recent requests: 
curl -X POST https://api.helicone.ai/v1/request/query \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "filter": "all",
    "limit": 10,
    "offset": 0,
    "sort": {
      "created_at": "desc"
    }
  }'

​
Filter by Model

Query requests for a specific model: 
curl -X POST https://api.helicone.ai/v1/request/query \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "filter": {
      "request": {
        "model": {
          "equals": "gpt-4"
        }
      }
    },
    "limit": 50
  }'

​
Filter by Custom Properties

Query requests with specific custom properties: 
curl -X POST https://api.helicone.ai/v1/request/query \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "filter": {
      "properties": {
        "environment": {
          "equals": "production"
        }
      }
    },
    "limit": 100,
    "sort": {
      "created_at": "desc"
    }
  }'

​
Filter by Date Range

Query requests within a specific time range: 
curl -X POST https://api.helicone.ai/v1/request/query \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "filter": {
      "left": {
        "request": {
          "created_at": {
            "gte": "2024-01-01T00:00:00Z"
          }
        }
      },
      "operator": "and",
      "right": {
        "request": {
          "created_at": {
            "lte": "2024-01-31T23:59:59Z"
          }
        }
      }
    },
    "limit": 100
  }'

​
Complex Filter with AND/OR

Query requests with multiple conditions: 
curl -X POST https://api.helicone.ai/v1/request/query \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "filter": {
      "left": {
        "request": {
          "model": {
            "equals": "gpt-4"
          }
        }
      },
      "operator": "and",
      "right": {
        "response": {
          "status": {
            "equals": 200
          }
        }
      }
    },
    "includeInputs": true,
    "isScored": true,
    "limit": 50
  }'

​
Response Example

{
  "data": [
    {
      "request_id": "req_123abc",
      "request_created_at": "2024-01-15T10:30:00Z",
      "request_path": "/v1/chat/completions",
      "request_model": "gpt-4",
      "request_user_id": "user_456",
      "request_properties": {
        "environment": "production",
        "app_version": "1.2.3"
      },
      "response_id": "res_789def",
      "response_created_at": "2024-01-15T10:30:02Z",
      "response_status": 200,
      "response_model": "gpt-4-0613",
      "provider": "OPENAI",
      "model": "gpt-4",
      "delay_ms": 2341,
      "time_to_first_token": 234,
      "total_tokens": 523,
      "prompt_tokens": 423,
      "completion_tokens": 100,
      "cost": 0.01569,
      "feedback_rating": true,
      "scores": {
        "accuracy": 0.95,
        "relevance": 0.88
      },
      "properties": {
        "environment": "production",
        "app_version": "1.2.3"
      }
    }
  ],
  "error": null
}

​
Notes

  • The maximum limit is 100 requests per query
  • Use pagination with offset and limit for large result sets
  • Filters support comparison operators: equals, not-equals, gte, lte, gt, lt, like, ilike, contains, not-contains
  • Complex filters can be built using nested left, operator, right structures
  • Setting includeInputs: true includes prompt template input variables
  • For high-volume queries, consider using the ClickHouse endpoint (/v1/request/query-clickhouse) for better performance

Build docs developers (and LLMs) love

Get started for freeTalk to us