Query Requests

curl --request POST \
  --url https://api.helicone.ai/v1/request/query \
  --header 'Content-Type: application/json' \
  --data '
{
  "filter": {},
  "offset": 123,
  "limit": 123,
  "sort": {},
  "isCached": true,
  "includeInputs": true,
  "isPartOfExperiment": true,
  "isScored": true
}
'

{
  "data": [
    {
      "request_id": "<string>",
      "request_created_at": "<string>",
      "request_body": {},
      "request_path": "<string>",
      "request_user_id": {},
      "request_properties": {},
      "request_model": {},
      "response_id": {},
      "response_created_at": {},
      "response_body": {},
      "response_status": 123,
      "response_model": {},
      "model_override": {},
      "provider": "<string>",
      "delay_ms": {},
      "time_to_first_token": {},
      "total_tokens": {},
      "prompt_tokens": {},
      "completion_tokens": {},
      "reasoning_tokens": {},
      "cost": {},
      "cache_enabled": true,
      "cache_reference_id": {},
      "scores": {},
      "feedback_rating": {},
      "properties": {}
    }
  ],
  "error": {}
}

POST

request

query

Query Requests

curl --request POST \
  --url https://api.helicone.ai/v1/request/query \
  --header 'Content-Type: application/json' \
  --data '
{
  "filter": {},
  "offset": 123,
  "limit": 123,
  "sort": {},
  "isCached": true,
  "includeInputs": true,
  "isPartOfExperiment": true,
  "isScored": true
}
'

{
  "data": [
    {
      "request_id": "<string>",
      "request_created_at": "<string>",
      "request_body": {},
      "request_path": "<string>",
      "request_user_id": {},
      "request_properties": {},
      "request_model": {},
      "response_id": {},
      "response_created_at": {},
      "response_body": {},
      "response_status": 123,
      "response_model": {},
      "model_override": {},
      "provider": "<string>",
      "delay_ms": {},
      "time_to_first_token": {},
      "total_tokens": {},
      "prompt_tokens": {},
      "completion_tokens": {},
      "reasoning_tokens": {},
      "cost": {},
      "cache_enabled": true,
      "cache_reference_id": {},
      "scores": {},
      "feedback_rating": {},
      "properties": {}
    }
  ],
  "error": {}
}

Query requests from your Helicone account with powerful filtering, sorting, and pagination capabilities. This endpoint uses Postgres as the data source.

For better performance with large datasets, consider using the Clickhouse Query endpoint.

Request Body

filter

RequestFilterNode

required

Filter criteria for requests. Can be a simple filter object, a complex filter tree with left, operator, and right properties, or "all" to return all requests.Supported filter tables:

request_response_rmt - Main request/response table
request - Request-specific fields
response - Response-specific fields
feedback - Feedback data
properties - Custom properties
values - Request values
sessions_request_response_rmt - Session data

Example simple filter:

{
  "request_response_rmt": {
    "request_created_at": {
      "gte": "2024-01-01T00:00:00Z"
    }
  }
}

Example complex filter:

{
  "left": {
    "request_response_rmt": {
      "model": { "equals": "gpt-4" }
    }
  },
  "operator": "and",
  "right": {
    "request_response_rmt": {
      "request_created_at": {
        "gte": "2024-01-01T00:00:00Z"
      }
    }
  }
}

offset

number

default:"0"

Number of records to skip for pagination.

limit

number

default:"10"

Maximum number of records to return (max 1000).

sort

object

Sort order for results. Specify field and direction.Example:

{
  "created_at": "desc"
}

isCached

boolean

Filter for cached requests only.

includeInputs

boolean

Include input data in the response.

isPartOfExperiment

boolean

Filter for requests that are part of an experiment.

isScored

boolean

Filter for requests that have scores attached.

Response

data

HeliconeRequest[]

Array of request objects matching the query criteria.

Show HeliconeRequest object

request_id

string

Unique identifier for the request.

request_created_at

string

ISO 8601 timestamp of when the request was created.

request_body

object

The request payload sent to the LLM provider.

request_path

string

API endpoint path that was called.

request_user_id

string | null

User ID associated with the request (from Helicone-User-Id header).

request_properties

object | null

Custom properties attached to the request.

request_model

string | null

Model name from the request.

response_id

string | null

Unique identifier for the response.

response_created_at

string | null

ISO 8601 timestamp of when the response was created.

response_body

object

The response payload from the LLM provider.

response_status

number

HTTP status code of the response.

response_model

string | null

Model name from the response.

model_override

string | null

Model override specified via Helicone-Model-Override header.

provider

string

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

delay_ms

number | null

Latency in milliseconds.

time_to_first_token

number | null

Time to first token in milliseconds (for streaming requests).

total_tokens

number | null

Total tokens used (prompt + completion).

prompt_tokens

number | null

Number of tokens in the prompt.

completion_tokens

number | null

Number of tokens in the completion.

reasoning_tokens

number | null

Number of reasoning tokens (for models like o1).

cost

number | null

Cost of the request in USD.

cache_enabled

boolean

Whether caching was enabled for this request.

cache_reference_id

string | null

Cache reference ID if cached.

scores

object | null

Scores attached to this request.

feedback_rating

boolean | null

Feedback rating (true for positive, false for negative).

properties

object

Custom properties attached to the request.

error

string | null

Error message if the request failed.

Examples

Basic Query

Query all requests from the last 7 days:

cURL

curl --request POST \
  --url https://api.helicone.ai/v1/request/query \
  --header 'Authorization: Bearer <HELICONE_API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
  "filter": {
    "request_response_rmt": {
      "request_created_at": {
        "gte": "2024-01-01T00:00:00Z"
      }
    }
  },
  "limit": 100,
  "offset": 0,
  "sort": {
    "created_at": "desc"
  }
}'

Filter by Model

Query all GPT-4 requests:

cURL

curl --request POST \
  --url https://api.helicone.ai/v1/request/query \
  --header 'Authorization: Bearer <HELICONE_API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
  "filter": {
    "request_response_rmt": {
      "model": {
        "equals": "gpt-4"
      }
    }
  },
  "limit": 50
}'

Filter by Custom Properties

Query requests with specific custom properties:

cURL

curl --request POST \
  --url https://api.helicone.ai/v1/request/query \
  --header 'Authorization: Bearer <HELICONE_API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
  "filter": {
    "request_response_rmt": {
      "properties": {
        "Environment": {
          "equals": "production"
        }
      }
    }
  },
  "limit": 100
}'

Complex Filter with AND/OR

Query GPT-4 requests in production from the last week:

cURL

curl --request POST \
  --url https://api.helicone.ai/v1/request/query \
  --header 'Authorization: Bearer <HELICONE_API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
  "filter": {
    "left": {
      "request_response_rmt": {
        "model": {
          "equals": "gpt-4"
        }
      }
    },
    "operator": "and",
    "right": {
      "left": {
        "request_response_rmt": {
          "request_created_at": {
            "gte": "2024-01-01T00:00:00Z"
          }
        }
      },
      "operator": "and",
      "right": {
        "request_response_rmt": {
          "properties": {
            "Environment": {
              "equals": "production"
            }
          }
        }
      }
    }
  },
  "limit": 100,
  "sort": {
    "created_at": "desc"
  }
}'

Pagination

Query requests with pagination:

cURL

curl --request POST \
  --url https://api.helicone.ai/v1/request/query \
  --header 'Authorization: Bearer <HELICONE_API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
  "filter": "all",
  "limit": 50,
  "offset": 100,
  "sort": {
    "created_at": "desc"
  }
}'

Filter Operators

The following operators are supported for different field types:

Text Fields

equals - Exact match
not-equals - Not equal to
like - Pattern match (case-sensitive)
ilike - Pattern match (case-insensitive)
contains - Contains substring
not-contains - Does not contain substring

Number Fields

equals - Equal to
not-equals - Not equal to
gte - Greater than or equal to
lte - Less than or equal to
gt - Greater than
lt - Less than

Timestamp Fields

equals - Exact timestamp match
gte - Greater than or equal to
lte - Less than or equal to
gt - Greater than
lt - Less than

Boolean Fields

equals - True or false

Get Request by ID

Retrieve a specific request by its ID

Add Feedback

Add feedback to a request

Add Properties

Add custom properties to a request

Add Scores

Add evaluation scores to a request

List Models Get Request by ID

​Request Body

​Response

​Examples

​Basic Query

​Filter by Model

​Filter by Custom Properties

​Complex Filter with AND/OR

​Pagination

​Filter Operators

​Text Fields

​Number Fields

​Timestamp Fields

​Boolean Fields

​Related Endpoints

Get Request by ID

Add Feedback

Add Properties

Add Scores

Request Body

Response

Examples

Basic Query

Filter by Model

Filter by Custom Properties

Complex Filter with AND/OR

Pagination

Filter Operators

Text Fields

Number Fields

Timestamp Fields

Boolean Fields

Related Endpoints