Skip to main content
Helicone OSS LLM Observability

Get Requests

Retrieve all requests visible in the request table at Helicone.
3 min read
post/v1/request/query-clickhouse
Request example
Response
post/v1/request/query-clickhouse
Warning

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

NPM Package (Recommended)

Use our CLI tool: npx @helicone/export - No installation required!

Python Example

See how to query requests using our Python SDK.

TypeScript Example

Learn to fetch requests with TypeScript/JavaScript.

Quick Start with NPM#

The easiest way to export data is using our CLI tool:

Key Features:

  • ✅ Auto-recovery from crashes with checkpoint system
  • ✅ Retry logic with exponential backoff
  • ✅ Progress tracking with ETA
  • ✅ Multiple output formats (JSON, JSONL, CSV)
  • ✅ Region support (US and EU)

See the full documentation for more options.

The following API is the same as the Get Requests API, but it is optimized for speed when querying large amount of data. This endpoint will timeout for point queries and is really slow when querying just a few requests.

The following API lets you get all of the requests that would be visible in the request table at helicone.ai/requests.

Premade examples 👇#

FilterDescription
Get Request by UserGet all the requests made by a user

Filter Structure#

Warning

Common Mistake: When filtering by custom properties, you MUST wrap them in a request_response_rmt object. Forgetting this wrapper will return empty results {"data":[],"error":null} even when data exists.

See the Filtering by Properties section below for complete examples.

Note

Important: Filters use an AST (Abstract Syntax Tree) structure where each condition must be a separate leaf node. You cannot combine multiple conditions in a single request_response_rmt object.

A filter is either a FilterLeaf or a FilterBranch, and can be composed of multiple filters generating an AST of ANDs/ORs.

TypeScript Types#

Simple Filter (Single Condition)#

Complex Filter (Multiple Conditions)#

Each condition is a separate leaf, connected with and/or operators:

Match All Requests (No Filter)#

Filtering by Date Range#

Note

Date ranges use inclusive bounds - both gte (greater than or equal) and lte (less than or equal) include the specified timestamps.

Single date filter:

Date range (start AND end):

Warning

Important: Each date condition must be a separate leaf! Don't put both gte and lte in the same object.

Available date operators:

  • gte - Greater than or equal (start date, inclusive)
  • lte - Less than or equal (end date, inclusive)
  • gt - Greater than (exclusive)
  • lt - Less than (exclusive)
  • equals - Exact timestamp match

Filtering by Properties#

Note

Important: When filtering by custom properties, you must nest the properties filter inside a request_response_rmt object.

Single property:

Combining property filter with other filters:

Complete Example: Date Range + Property Filter#

This example shows how to combine a date range with a property filter:

Available Filter Operators#

Different fields support different operators:

Text fields (model, user_id, provider, etc.):

  • equals / not-equals
  • like / ilike (case-insensitive)
  • contains / not-contains

Number fields (status, latency, cost, etc.):

  • equals / not-equals
  • gte / lte / gt / lt

Timestamp fields (request_created_at, response_created_at):

  • equals
  • gte / lte / gt / lt

Troubleshooting#

Getting Empty Results {"data":[],"error":null}#

If you're getting empty results when you know data exists, check these common issues:

1. Missing request_response_rmt wrapper for properties

❌ WRONG - Properties without wrapper

Result: Empty data even though the property exists

✅ CORRECT - Properties with request_response_rmt wrapper

Result: Returns all requests with that property value

2. Using wrong API endpoint structure

This endpoint (/query-clickhouse) requires request_response_rmt wrapper for ALL filters including properties. If you're using the legacy /query endpoint, the filter structure is different - see Get Requests (Legacy).

3. Wrong region

Make sure you're using the correct regional endpoint:

  • US: https://api.helicone.ai/v1/request/query-clickhouse
  • EU: https://eu.api.helicone.ai/v1/request/query-clickhouse

4. Property name doesn't match

Property names are case-sensitive. Check your exact property name in the Helicone dashboard.

Authorization

Authorizationstringheaderrequired#
Bearer token authentication. Format: 'Bearer YOUR_API_KEY'

Body

application/json
filterobject · enum<string>required#
Show child attributes
offsetnumber#
limitnumber#
sortobject#
Show child attributes
randomenum<boolean>#
Options:true
created_atenum<string>#
Options:ascdesc
cache_created_atenum<string>#
Options:ascdesc
latencyenum<string>#
Options:ascdesc
last_activeenum<string>#
Options:ascdesc
total_tokensenum<string>#
Options:ascdesc
completion_tokensenum<string>#
Options:ascdesc
prompt_tokensenum<string>#
Options:ascdesc
user_idenum<string>#
Options:ascdesc
body_modelenum<string>#
Options:ascdesc
is_cachedenum<string>#
Options:ascdesc
request_promptenum<string>#
Options:ascdesc
response_textenum<string>#
Options:ascdesc
propertiesobject#
Show child attributes
{key}enum<string>#
Options:ascdesc
valuesobject#
Show child attributes
{key}enum<string>#
Options:ascdesc
costenum<string>#
Options:ascdesc
time_to_first_tokenenum<string>#
Options:ascdesc
isCachedboolean#
includeInputsboolean#
isPartOfExperimentboolean#
isScoredboolean#

Responses

application/json
200
Ok
Get All Available ModelsGet Requests (Point Queries)