---
title: "Eval Results Query"
method: POST
path: "/v2/{entity}/{project}/eval_results/query"
tags: ["Eval Results"]
---

# Eval Results Query

`POST /v2/{entity}/{project}/eval_results/query`

Read grouped evaluation result rows for one or more evaluations.

## Path parameters

- `entity` string, required
- `project` string, required

## Request body

- EvalResultsQueryBody
  - `evaluation_call_ids` string[], nullable — Evaluation root call IDs to include.
  - `evaluation_run_ids` string[], nullable — Alias for evaluation call IDs from the Evaluation Runs API.
  - `require_intersection` boolean — When true, only include rows present in all requested evaluations.
  - `include_raw_data_rows` boolean — When true, populate raw_data_row on each result row. Inline rows are returned as their dict value; dataset-referenced rows are returned as the ref string unless resolve_row_refs is also true.
  - `resolve_row_refs` boolean — When true (requires include_raw_data_rows=True), resolve dataset-row reference strings to actual row data via a table lookup. When false, dataset-row refs are returned as-is.
  - `include_rows` boolean — When true, include grouped row/trial data in `rows` and compute `total_rows` for the requested row-level view.
  - `include_summary` boolean — When true, include aggregated scorer/evaluation summary data in `summary`.
  - `summary_require_intersection` boolean, nullable — Optional intersection behavior for the summary section. When null, the value of `require_intersection` is used.
  - `include_predict_and_score_children` boolean — When true (default), fetch child calls (predict/score) of each predict_and_score call to populate predict_call_id, scorer_call_ids, and more precise latency/token data. When false, these fields are derived from the predict_and_score call itself (predict_call_id and scorer_call_ids will be null/empty).
  - `include_costs` boolean — When true, enrich the predict-and-score child calls with cost so the summary can report predict-only `predict_total_cost`. Opt-in: other callers skip the cost computation.
  - `sort_by` EvalResultsSortBy[], nullable — Sort specification for result rows. Supported field prefixes: scores.<name>, inputs.<path>, outputs.<path>. When null, rows are sorted by row_digest ASC.
    - `field` string, required
    - `direction` 'asc' | 'desc', required
    - `evaluation_call_id` string, nullable — Scope the sort to a specific evaluation's scores.
    - `mode` 'value' | 'difference' — When 'value', sort by the field value for the specified evaluation. When 'difference', sort by max-min spread of the field across all evaluations (evaluation_call_id is ignored).
  - `filters` EvalResultsFilter[], nullable — Filters applied to grouped rows. Multiple filters are AND'd together.
    - `evaluation_call_id` string, nullable — When set, filter fields are scoped to this evaluation's data.
    - `query` Query, required
      - `$expr` union, required
        - AndOperation — Logical AND. All conditions must evaluate to true. Example:
          - `$and` union[], required
            - union
              - …
        - unknown
        - unknown
        - unknown
        - unknown
        - unknown
        - unknown
        - unknown
        - unknown
        - unknown
  - `filter_logic_operator` 'and' | 'or' — How to combine filters across evaluations: 'and' (Match All - row must match in ALL evals) or 'or' (Match Any - row must match in ANY eval). Defaults to 'or' (Match Any).
  - `limit` integer, nullable — Optional row-level page size applied after grouping and intersection.
  - `offset` integer — Optional row-level page offset applied after grouping and intersection.

## Response `200`

Successful Response

- EvalResultsQueryRes
  - `rows` EvalResultsRow[], required
    - `row_digest` string, required
    - `raw_data_row` unknown
    - `evaluations` EvalResultsRowEvaluation[]
      - `evaluation_call_id` string, required
      - `trials` EvalResultsTrial[]
        - unknown
  - `total_rows` integer, required
  - `summary` EvalResultsSummaryRes
    - `row_count` integer
    - `evaluations` EvalResultsEvaluationSummary[]
      - `evaluation_call_id` string, required
      - `trial_count` integer
      - `scorer_stats` EvalResultsScorerStats[]
        - unknown
      - `predict_total_tokens` integer, nullable — Sum of per-trial predict-only token usage for this evaluation (the model's predict() tokens only, excluding LLM-as-a-judge scorer usage); None when no trial reports usage.
      - `predict_total_cost` number, nullable — Sum of per-trial predict-only cost for this evaluation (the model's predict() cost only, excluding LLM-as-a-judge scorer cost); None when no trial reports cost.
      - `evaluation_ref` string, nullable
      - `model_ref` string, nullable
      - `display_name` string, nullable
      - `trace_id` string, nullable
      - `started_at` string, nullable
  - `warnings` string[] — Non-fatal warnings (e.g. failed to resolve dataset row refs).

## Other responses

- `422` — Validation Error

---

[API](https://skmtc.net/wandb/apis/serverless-training.md) · [All operations](https://skmtc.net/wandb/apis/serverless-training/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/wandb/serverless-training/revisions/8d8d96fc0fd3/schema)