Query Requests

Query and filter requests with advanced filtering and pagination

POST /v1/request/query

Query Requests

cURL

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
}
'

200

{
  "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

Related Endpoints

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