Query Evaluations

Search and filter through evaluation results with advanced filtering capabilities

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
}