Skip to main content
This endpoint allows you to query and retrieve evaluation data for your requests. Use filters to narrow down results by specific criteria and time ranges.

​
Use Cases

  • Retrieve evaluation scores for analysis
  • Filter evaluations by time period
  • Get evaluation metrics for specific requests
  • Monitor evaluation trends over time

​
Request Body

The request accepts an EvalQueryParams object with the following structure:
​
filter
EvalFilterNode
required
Filter criteria for evaluations. Can be “all” to retrieve all evaluations, or a filter tree structure to specify conditions.
​
timeFilter
object
required
Time range for filtering evaluations.
​
timeFilter.start
string
required
Start time in ISO 8601 format (e.g., “2024-01-01T00:00:00Z”)
​
timeFilter.end
string
required
End time in ISO 8601 format (e.g., “2024-01-31T23:59:59Z”)
​
offset
number
Number of records to skip for pagination (default: 0)
​
limit
number
Maximum number of records to return (default: 100)
​
timeZoneDifference
number
Time zone difference in minutes from UTC

​
Response

Returns a Result object containing an array of Eval objects.
​
data
Eval[]
Array of evaluation objects
​
data[].name
string
Name of the evaluation metric
​
data[].averageScore
number
Average score across all evaluations
​
data[].minScore
number
Minimum score recorded
​
data[].maxScore
number
Maximum score recorded
​
data[].count
number
Total number of evaluations
​
data[].overTime
array
Count of evaluations over time
​
data[].averageOverTime
array
Average scores over time
​
error
string | null
Error message if the request failed, null otherwise

​
Example Request

curl --request POST \
  --url https://api.helicone.ai/v1/evals/query \
  --header 'Authorization: Bearer <YOUR_API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
    "filter": "all",
    "timeFilter": {
      "start": "2024-01-01T00:00:00Z",
      "end": "2024-01-31T23:59:59Z"
    },
    "offset": 0,
    "limit": 100
  }'

​
Example Response

{
  "data": [
    {
      "name": "accuracy",
      "averageScore": 0.85,
      "minScore": 0.65,
      "maxScore": 0.98,
      "count": 150,
      "overTime": [
        { "date": "2024-01-01", "count": 10 },
        { "date": "2024-01-02", "count": 15 }
      ],
      "averageOverTime": [
        { "date": "2024-01-01", "value": 0.82 },
        { "date": "2024-01-02", "value": 0.87 }
      ]
    }
  ],
  "error": null
}