---
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`

## Request

- Base URL: `https://trace.wandb.ai` (the document declares no server; this is the origin it was published from)
- URL: `https://trace.wandb.ai/v2/{entity}/{project}/eval_results/query`
- Auth: none declared

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, price each trial's predict call so rows and summary report predict-only cost (`total_cost` / `predict_total_cost`); scorer costs are excluded. 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": [ {"$eq": [{"$getField": "op_name"}, {"$literal": "predict"}]}, {"$gt": [{"$getField": "summary.usage.tokens"}, {"$literal": 1000}]} ] } ```
          - `$and` union[], required
            - union
              - …
        - OrOperation: Logical OR. At least one condition must be true. Example: ``` { "$or": [ {"$eq": [{"$getField": "op_name"}, {"$literal": "a"}]}, {"$eq": [{"$getField": "op_name"}, {"$literal": "b"}]} ] } ```
          - `$or` union[], required
            - union
              - …
        - NotOperation: Logical NOT. Inverts the condition. Example: ``` { "$not": [ {"$eq": [{"$getField": "op_name"}, {"$literal": "debug"}]} ] } ```
          - `$not` unknown[], required
            - unknown
        - EqOperation: Equality check between two operands. Example: ``` { "$eq": [{"$getField": "op_name"}, {"$literal": "predict"}] } ```
          - `$eq` unknown[], required
            - unknown
        - GtOperation: Greater than comparison. Example: ``` { "$gt": [{"$getField": "summary.usage.tokens"}, {"$literal": 100}] } ```
          - `$gt` unknown[], required
            - unknown
        - LtOperation: Less than comparison. Example: ``` { "$lt": [{"$getField": "summary.usage.tokens"}, {"$literal": 100}] } ```
          - `$lt` unknown[], required
            - unknown
        - GteOperation: Greater than or equal comparison. Example: ``` { "$gte": [{"$getField": "summary.usage.tokens"}, {"$literal": 100}] } ```
          - `$gte` unknown[], required
            - unknown
        - LteOperation: Less than or equal comparison. Example: ``` { "$lte": [{"$getField": "summary.usage.tokens"}, {"$literal": 100}] } ```
          - `$lte` unknown[], required
            - unknown
        - InOperation: Membership check. Returns true if the left operand is in the list provided as the second operand. Example: ``` { "$in": [ {"$getField": "op_name"}, [{"$literal": "predict"}, {"$literal": "generate"}] ] } ```
          - `$in` unknown[], required
            - unknown
        - ContainsOperation: Case-insensitive substring match. Not part of MongoDB. Weave-specific addition. Example: ``` { "$contains": { "input": {"$getField": "display_name"}, "substr": {"$literal": "llm"}, "case_insensitive": true } } ```
          - `$contains` ContainsSpec, required: Specification for the `$contains` operation. - `input`: The string to search. - `substr`: The substring to search for. - `case_insensitive`: If true, match is case-insensitive.
            - `input` union, required
              - …
            - `substr` union, required
              - …
            - `case_insensitive` boolean, nullable
  - `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, required
    - `evaluations` EvalResultsRowEvaluation[], required
      - `evaluation_call_id` string, required
      - `trials` EvalResultsTrial[], required
        - `predict_and_score_call_id` string, required
        - `predict_call_id` string, nullable, required
        - `model_output` unknown, required
        - `scores` object, required
        - `model_latency_seconds` number, nullable, required
        - `total_tokens` integer, nullable, required
        - `total_cost` number, nullable, required
        - `scorer_call_ids` object, required
        - `genai_span_ref` GenAISpanRef[], nullable, required
          - `trace_id` string, required
          - `span_id` string, required
  - `total_rows` integer, required
  - `summary` EvalResultsSummaryRes, required
    - `row_count` integer, required
    - `evaluations` EvalResultsEvaluationSummary[], required
      - `evaluation_call_id` string, required
      - `trial_count` integer, required
      - `scorer_stats` EvalResultsScorerStats[], required
        - `scorer_key` string, required
        - `path` string, nullable, required: Dot-joined subpath for nested dimensions, e.g. 'passed' for token_distance.passed. None for root-level scalar scorers.
        - `value_type` 'binary' | 'continuous' | 'text', nullable, required: Type of the leaf value: binary (bool), continuous (number), or text (string).
        - `trial_count` integer, required
        - `numeric_count` integer, required
        - `numeric_mean` number, nullable, required
        - `pass_true_count` integer, required
        - `pass_known_count` integer, required
        - `pass_rate` number, nullable, required
        - `pass_signal_coverage` number, nullable, required
      - `predict_total_tokens` integer, nullable, required: 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, required: 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, required
      - `model_ref` string, nullable, required
      - `display_name` string, nullable, required
      - `trace_id` string, nullable, required
      - `started_at` string, nullable, required
  - `warnings` string[], required: Non-fatal warnings (e.g. failed to resolve dataset row refs).

## Other responses

- `422`: Validation Error

## Changes

- **2026-10-16** `dd89fadfe4e4`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/wandb/apis/fastapi/changes/v2/:entity/:project/eval_results/query/post.md)

---

[API](https://skmtc.dev/wandb/apis/fastapi.md) - [All operations](https://skmtc.dev/wandb/apis/fastapi/llms.txt) - [OpenAPI document](https://skmtc.dev/wandb/apis/fastapi/revisions/f7643c49bf2e?raw)