Query Requests

Query and filter requests with advanced filtering and pagination

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

Show Request Object

request_id · string

Unique identifier for the request

request_created_at · string

Timestamp when the request was created (ISO 8601)

request_body · object

The request payload sent to the LLM provider

request_path · string

API endpoint path (e.g., “/v1/chat/completions”)

request_user_id · string

User identifier associated with the request

request_properties · object

Custom properties attached to the request

request_model · string

Model requested in the API call

response_id · string

Unique identifier for the response

response_created_at · string

Timestamp when the response was received

response_body · object

The response payload from the LLM provider

response_status · number

HTTP status code of the response

response_model · string

Actual model used by the provider

provider · string

LLM provider name (e.g., “OPENAI”, “ANTHROPIC”, “AZURE”)

model · string

Model identifier

delay_ms · number

Request latency in milliseconds

time_to_first_token · number

Time to first token in milliseconds (for streaming)

total_tokens · number

Total tokens used (prompt + completion)

prompt_tokens · number

Number of tokens in the prompt

completion_tokens · number

Number of tokens in the completion

cost · number

Cost of the request in USD

prompt_id · string

ID of the prompt template used

prompt_version · string

Version of the prompt template used

feedback_rating · boolean

User feedback rating (true for positive, false for negative)

scores · object

Evaluation scores as key-value pairs

properties · object

All custom properties for the request

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