Skip to main content
POST
/
v1
/
request
/
query-clickhouse
cURL
curl --request POST \
  --url https://api.helicone.ai/v1/request/query-clickhouse \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "filter": {
    "request_response_rmt": {
      "country_code": {
        "not-equals": "<string>",
        "equals": "<string>",
        "like": "<string>",
        "ilike": "<string>",
        "contains": "<string>",
        "not-contains": "<string>"
      },
      "latency": {
        "not-equals": 123,
        "equals": 123,
        "gte": 123,
        "lte": 123,
        "lt": 123,
        "gt": 123
      },
      "cost": {
        "not-equals": 123,
        "equals": 123,
        "gte": 123,
        "lte": 123,
        "lt": 123,
        "gt": 123
      },
      "provider": {
        "not-equals": "<string>",
        "equals": "<string>",
        "like": "<string>",
        "ilike": "<string>",
        "contains": "<string>",
        "not-contains": "<string>"
      },
      "time_to_first_token": {
        "not-equals": 123,
        "equals": 123,
        "gte": 123,
        "lte": 123,
        "lt": 123,
        "gt": 123
      },
      "status": {
        "not-equals": 123,
        "equals": 123,
        "gte": 123,
        "lte": 123,
        "lt": 123,
        "gt": 123
      },
      "request_created_at": {
        "equals": "2023-11-07T05:31:56Z",
        "gte": "2023-11-07T05:31:56Z",
        "lte": "2023-11-07T05:31:56Z",
        "lt": "2023-11-07T05:31:56Z",
        "gt": "2023-11-07T05:31:56Z"
      },
      "response_created_at": {
        "equals": "2023-11-07T05:31:56Z",
        "gte": "2023-11-07T05:31:56Z",
        "lte": "2023-11-07T05:31:56Z",
        "lt": "2023-11-07T05:31:56Z",
        "gt": "2023-11-07T05:31:56Z"
      },
      "model": {
        "not-equals": "<string>",
        "equals": "<string>",
        "like": "<string>",
        "ilike": "<string>",
        "contains": "<string>",
        "not-contains": "<string>"
      },
      "user_id": {
        "not-equals": "<string>",
        "equals": "<string>",
        "like": "<string>",
        "ilike": "<string>",
        "contains": "<string>",
        "not-contains": "<string>"
      },
      "organization_id": {
        "not-equals": "<string>",
        "equals": "<string>",
        "like": "<string>",
        "ilike": "<string>",
        "contains": "<string>",
        "not-contains": "<string>"
      },
      "node_id": {
        "not-equals": "<string>",
        "equals": "<string>",
        "like": "<string>",
        "ilike": "<string>",
        "contains": "<string>",
        "not-contains": "<string>"
      },
      "job_id": {
        "not-equals": "<string>",
        "equals": "<string>",
        "like": "<string>",
        "ilike": "<string>",
        "contains": "<string>",
        "not-contains": "<string>"
      },
      "threat": {
        "equals": true
      },
      "request_id": {
        "not-equals": "<string>",
        "equals": "<string>",
        "like": "<string>",
        "ilike": "<string>",
        "contains": "<string>",
        "not-contains": "<string>"
      },
      "prompt_tokens": {
        "not-equals": 123,
        "equals": 123,
        "gte": 123,
        "lte": 123,
        "lt": 123,
        "gt": 123
      },
      "completion_tokens": {
        "not-equals": 123,
        "equals": 123,
        "gte": 123,
        "lte": 123,
        "lt": 123,
        "gt": 123
      },
      "prompt_cache_read_tokens": {
        "not-equals": 123,
        "equals": 123,
        "gte": 123,
        "lte": 123,
        "lt": 123,
        "gt": 123
      },
      "prompt_cache_write_tokens": {
        "not-equals": 123,
        "equals": 123,
        "gte": 123,
        "lte": 123,
        "lt": 123,
        "gt": 123
      },
      "total_tokens": {
        "not-equals": 123,
        "equals": 123,
        "gte": 123,
        "lte": 123,
        "lt": 123,
        "gt": 123
      },
      "target_url": {
        "not-equals": "<string>",
        "equals": "<string>",
        "like": "<string>",
        "ilike": "<string>",
        "contains": "<string>",
        "not-contains": "<string>"
      },
      "property_key": {
        "equals": "<string>"
      },
      "properties": {},
      "search_properties": {},
      "scores": {},
      "scores_column": {
        "not-equals": "<string>",
        "equals": "<string>",
        "like": "<string>",
        "ilike": "<string>",
        "contains": "<string>",
        "not-contains": "<string>"
      },
      "request_body": {
        "contains": "<string>"
      },
      "response_body": {
        "contains": "<string>"
      },
      "cache_enabled": {
        "equals": true
      },
      "cache_reference_id": {
        "not-equals": "<string>",
        "equals": "<string>",
        "like": "<string>",
        "ilike": "<string>",
        "contains": "<string>",
        "not-contains": "<string>"
      },
      "cached": {
        "equals": true
      },
      "assets": {
        "not-equals": "<string>",
        "equals": "<string>",
        "like": "<string>",
        "ilike": "<string>",
        "contains": "<string>",
        "not-contains": "<string>"
      },
      "helicone-score-feedback": {
        "equals": true
      },
      "prompt_id": {
        "not-equals": "<string>",
        "equals": "<string>",
        "like": "<string>",
        "ilike": "<string>",
        "contains": "<string>",
        "not-contains": "<string>"
      },
      "prompt_version": {
        "not-equals": "<string>",
        "equals": "<string>",
        "like": "<string>",
        "ilike": "<string>",
        "contains": "<string>",
        "not-contains": "<string>"
      },
      "request_referrer": {
        "not-equals": "<string>",
        "equals": "<string>",
        "like": "<string>",
        "ilike": "<string>",
        "contains": "<string>",
        "not-contains": "<string>"
      },
      "is_passthrough_billing": {
        "equals": true
      }
    },
    "response": {
      "body_tokens": {
        "not-equals": 123,
        "equals": 123,
        "gte": 123,
        "lte": 123,
        "lt": 123,
        "gt": 123
      },
      "body_model": {
        "not-equals": "<string>",
        "equals": "<string>",
        "like": "<string>",
        "ilike": "<string>",
        "contains": "<string>",
        "not-contains": "<string>"
      },
      "body_completion": {
        "not-equals": "<string>",
        "equals": "<string>",
        "like": "<string>",
        "ilike": "<string>",
        "contains": "<string>",
        "not-contains": "<string>"
      },
      "status": {
        "not-equals": 123,
        "equals": 123,
        "gte": 123,
        "lte": 123,
        "lt": 123,
        "gt": 123
      },
      "model": {
        "not-equals": "<string>",
        "equals": "<string>",
        "like": "<string>",
        "ilike": "<string>",
        "contains": "<string>",
        "not-contains": "<string>"
      }
    },
    "request": {
      "prompt": {
        "not-equals": "<string>",
        "equals": "<string>",
        "like": "<string>",
        "ilike": "<string>",
        "contains": "<string>",
        "not-contains": "<string>"
      },
      "created_at": {
        "equals": "<string>",
        "gte": "<string>",
        "lte": "<string>",
        "lt": "<string>",
        "gt": "<string>"
      },
      "user_id": {
        "not-equals": "<string>",
        "equals": "<string>",
        "like": "<string>",
        "ilike": "<string>",
        "contains": "<string>",
        "not-contains": "<string>"
      },
      "auth_hash": {
        "not-equals": "<string>",
        "equals": "<string>",
        "like": "<string>",
        "ilike": "<string>",
        "contains": "<string>",
        "not-contains": "<string>"
      },
      "org_id": {
        "not-equals": "<string>",
        "equals": "<string>",
        "like": "<string>",
        "ilike": "<string>",
        "contains": "<string>",
        "not-contains": "<string>"
      },
      "id": {
        "not-equals": "<string>",
        "equals": "<string>",
        "like": "<string>",
        "ilike": "<string>",
        "contains": "<string>",
        "not-contains": "<string>"
      },
      "node_id": {
        "not-equals": "<string>",
        "equals": "<string>",
        "like": "<string>",
        "ilike": "<string>",
        "contains": "<string>",
        "not-contains": "<string>"
      },
      "model": {
        "not-equals": "<string>",
        "equals": "<string>",
        "like": "<string>",
        "ilike": "<string>",
        "contains": "<string>",
        "not-contains": "<string>"
      },
      "modelOverride": {
        "not-equals": "<string>",
        "equals": "<string>",
        "like": "<string>",
        "ilike": "<string>",
        "contains": "<string>",
        "not-contains": "<string>"
      },
      "path": {
        "not-equals": "<string>",
        "equals": "<string>",
        "like": "<string>",
        "ilike": "<string>",
        "contains": "<string>",
        "not-contains": "<string>"
      },
      "country_code": {
        "not-equals": "<string>",
        "equals": "<string>",
        "like": "<string>",
        "ilike": "<string>",
        "contains": "<string>",
        "not-contains": "<string>"
      },
      "prompt_id": {
        "not-equals": "<string>",
        "equals": "<string>",
        "like": "<string>",
        "ilike": "<string>",
        "contains": "<string>",
        "not-contains": "<string>"
      }
    },
    "feedback": {
      "id": {
        "not-equals": 123,
        "equals": 123,
        "gte": 123,
        "lte": 123,
        "lt": 123,
        "gt": 123
      },
      "created_at": {
        "equals": "<string>",
        "gte": "<string>",
        "lte": "<string>",
        "lt": "<string>",
        "gt": "<string>"
      },
      "rating": {
        "equals": true
      },
      "response_id": {
        "not-equals": "<string>",
        "equals": "<string>",
        "like": "<string>",
        "ilike": "<string>",
        "contains": "<string>",
        "not-contains": "<string>"
      }
    },
    "sessions_request_response_rmt": {
      "session_session_id": {
        "not-equals": "<string>",
        "equals": "<string>",
        "like": "<string>",
        "ilike": "<string>",
        "contains": "<string>",
        "not-contains": "<string>"
      },
      "session_session_name": {
        "not-equals": "<string>",
        "equals": "<string>",
        "like": "<string>",
        "ilike": "<string>",
        "contains": "<string>",
        "not-contains": "<string>"
      },
      "session_total_cost": {
        "not-equals": 123,
        "equals": 123,
        "gte": 123,
        "lte": 123,
        "lt": 123,
        "gt": 123
      },
      "session_total_tokens": {
        "not-equals": 123,
        "equals": 123,
        "gte": 123,
        "lte": 123,
        "lt": 123,
        "gt": 123
      },
      "session_prompt_tokens": {
        "not-equals": 123,
        "equals": 123,
        "gte": 123,
        "lte": 123,
        "lt": 123,
        "gt": 123
      },
      "session_completion_tokens": {
        "not-equals": 123,
        "equals": 123,
        "gte": 123,
        "lte": 123,
        "lt": 123,
        "gt": 123
      },
      "session_total_requests": {
        "not-equals": 123,
        "equals": 123,
        "gte": 123,
        "lte": 123,
        "lt": 123,
        "gt": 123
      },
      "session_created_at": {
        "equals": "2023-11-07T05:31:56Z",
        "gte": "2023-11-07T05:31:56Z",
        "lte": "2023-11-07T05:31:56Z",
        "lt": "2023-11-07T05:31:56Z",
        "gt": "2023-11-07T05:31:56Z"
      },
      "session_latest_request_created_at": {
        "equals": "2023-11-07T05:31:56Z",
        "gte": "2023-11-07T05:31:56Z",
        "lte": "2023-11-07T05:31:56Z",
        "lt": "2023-11-07T05:31:56Z",
        "gt": "2023-11-07T05:31:56Z"
      },
      "session_tag": {
        "not-equals": "<string>",
        "equals": "<string>",
        "like": "<string>",
        "ilike": "<string>",
        "contains": "<string>",
        "not-contains": "<string>"
      }
    },
    "properties": {},
    "values": {}
  },
  "offset": 123,
  "limit": 123,
  "sort": {
    "random": true,
    "created_at": "asc",
    "cache_created_at": "asc",
    "latency": "asc",
    "last_active": "asc",
    "total_tokens": "asc",
    "completion_tokens": "asc",
    "prompt_tokens": "asc",
    "user_id": "asc",
    "body_model": "asc",
    "is_cached": "asc",
    "request_prompt": "asc",
    "response_text": "asc",
    "properties": {},
    "values": {},
    "cost": "asc",
    "time_to_first_token": "asc"
  },
  "isCached": true,
  "includeInputs": true,
  "isPartOfExperiment": true,
  "isScored": true
}
'
{
  "filter": {},
  "isCached": false,
  "limit": 10,
  "offset": 0,
  "sort": {
    "created_at": "desc"
  },
  "isScored": false,
  "isPartOfExperiment": false
}
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: 
# Export with npx (no installation required)
HELICONE_API_KEY="your-api-key" npx @helicone/export --start-date 2024-01-01 --limit 10000 --include-body

# With property filter
HELICONE_API_KEY="your-api-key" npx @helicone/export --property appname=MyApp --format csv --include-body

# With date range and full bodies
HELICONE_API_KEY="your-api-key" npx @helicone/export --start-date 2024-08-01 --end-date 2024-08-31 --include-body

# Export from EU region
HELICONE_API_KEY="your-eu-api-key" npx @helicone/export --region eu --limit 10000 --include-body
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

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.
// ❌ WRONG - Missing request_response_rmt wrapper
{
  "filter": {
    "properties": {
      "ticket-id": { "equals": "..." }
    }
  }
}

// ✅ CORRECT - Properties wrapped in request_response_rmt
{
  "filter": {
    "request_response_rmt": {
      "properties": {
        "ticket-id": { "equals": "..." }
      }
    }
  }
}
See the Filtering by Properties section below for complete examples.
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

export interface FilterBranch {
  left: FilterNode;
  operator: "or" | "and";
  right: FilterNode;
}

export type FilterLeaf = {
  request_response_rmt: {
    [field: string]: {
      [operator: string]: any;
    };
  };
};

export type FilterNode = FilterLeaf | FilterBranch | "all";

​
Simple Filter (Single Condition)

{
  "filter": {
    "request_response_rmt": {
      "model": {
        "contains": "gpt-4"
      }
    }
  }
}

​
Complex Filter (Multiple Conditions)

Each condition is a separate leaf, connected with and/or operators: 
{
  "filter": {
    "left": {
      "request_response_rmt": {
        "model": {
          "contains": "gpt-4"
        }
      }
    },
    "operator": "and",
    "right": {
      "request_response_rmt": {
        "user_id": {
          "equals": "[email protected]"
        }
      }
    }
  }
}

​
Match All Requests (No Filter)

{
  "filter": "all"
}

​
Filtering by Date Range

Date ranges use inclusive bounds - both gte (greater than or equal) and lte (less than or equal) include the specified timestamps.
Single date filter: 
{
  "filter": {
    "request_response_rmt": {
      "request_created_at": {
        "gte": "2024-01-01T00:00:00Z"
      }
    }
  }
}
Date range (start AND end):
Important: Each date condition must be a separate leaf! Don’t put both gte and lte in the same object.
{
  "filter": {
    "left": {
      "request_response_rmt": {
        "request_created_at": {
          "gte": "2024-01-01T00:00:00Z"
        }
      }
    },
    "operator": "and",
    "right": {
      "request_response_rmt": {
        "request_created_at": {
          "lte": "2024-12-31T23:59:59Z"
        }
      }
    }
  }
}
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

Important: When filtering by custom properties, you must nest the properties filter inside a request_response_rmt object.
Single property: 
{
  "filter": {
    "request_response_rmt": {
      "properties": {
        "environment": {
          "equals": "production"
        }
      }
    }
  }
}
Combining property filter with other filters: 
{
  "filter": {
    "left": {
      "request_response_rmt": {
        "model": {
          "equals": "gpt-4"
        }
      }
    },
    "operator": "and",
    "right": {
      "request_response_rmt": {
        "properties": {
          "environment": {
            "equals": "production"
          }
        }
      }
    }
  }
}

​
Complete Example: Date Range + Property Filter

This example shows how to combine a date range with a property filter: 
{
  "filter": {
    "left": {
      "left": {
        "request_response_rmt": {
          "request_created_at": {
            "gte": "2024-08-01T00:00:00Z"
          }
        }
      },
      "operator": "and",
      "right": {
        "request_response_rmt": {
          "request_created_at": {
            "lte": "2024-08-31T23:59:59Z"
          }
        }
      }
    },
    "operator": "and",
    "right": {
      "request_response_rmt": {
        "properties": {
          "appname": {
            "equals": "LlamaCoder"
          }
        }
      }
    }
  },
  "limit": 100,
  "offset": 0
}

​
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 
curl --request POST \
  --url https://api.helicone.ai/v1/request/query-clickhouse \
  --header "Content-Type: application/json" \
  --header "authorization: Bearer $HELICONE_API_KEY" \
  --data '{
  "filter": {
    "properties": {
      "ticket-id": {
        "equals": "ba9bf8b3-c04f-41ad-9362-37f8feff7e57"
      }
    }
  }
}'
Result: Empty data even though the property exists
curl --request POST \
  --url https://api.helicone.ai/v1/request/query-clickhouse \
  --header "Content-Type: application/json" \
  --header "authorization: Bearer $HELICONE_API_KEY" \
  --data '{
  "filter": {
    "request_response_rmt": {
      "properties": {
        "ticket-id": {
          "equals": "ba9bf8b3-c04f-41ad-9362-37f8feff7e57"
        }
      }
    }
  }
}'
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.

Authorizations

​
Authorization
string
header
required

Bearer token authentication. Format: 'Bearer YOUR_API_KEY'

Body

application/json
​
filter
required

From T, pick a set of properties whose keys are in the union K

​
offset
number<double>
​
limit
number<double>
​
sort
object
​
isCached
boolean
​
includeInputs
boolean
​
isPartOfExperiment
boolean
​
isScored
boolean

Response

200 - application/json

Ok

​
data
object[]
required
​
error
enum<number> | null
required
Available options: