Skip to main content

List scores

POST 
/api/v1/evals/list-scores

Lists recorded scores across their sources and evaluation targets.

Filtering by what the rating is about​

Section ID: DOC-IS-evaluation-api-listScores#filtering-by-what-the-rating-is-about

conversationId and profileId answer "every rating on this conversation" and "every rating on turns this agent profile produced". Each is decided per score — on the score's own metadata, or on the trace it scores when the metadata does not say — and combining them is an intersection. conversationId accepts a bare thread id and qualifies it with your verified tenant.

Reading the result honestly​

Section ID: DOC-IS-evaluation-api-listScores#reading-the-result-honestly

filterNarrowed matters when you paginate. Some filters cannot be applied by the underlying store, so rows are removed after they are fetched: conversationId, profileId, userId, the platform source values the store does not distinguish, and the rows of the filters array. The response sets filterNarrowed: true only when at least one row was removed from the pages fetched for this response. It can remain false or be omitted even when these filters were evaluated. A page may be shorter than pageSize or empty while cursorPage.nextCursor still leads to more matches — keep following the cursor until it is omitted rather than stopping at a short page. A false or omitted flag is not a complete-history or consistent-snapshot guarantee. There is no total.

Deduplicate IDs across pages when collecting a report.

Score filters and result coverage​

Section ID: DOC-IS-evaluation-api-listScores#score-filters-and-result-coverage

Current min/max score filters treat zero as unset; to apply a zero bound, collect the relevant permitted pages and filter in your application. See list-scores for supported filters.

The following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action.

Use this in a guide: Find out why a customer’s reply was slow · Feedback and score attribution

Request​

Responses​

OK

Schema-valid request illustration; replace example identifiers and confirm operation prerequisites.​

Section ID: DOC-IS-evaluation-api-listScores#example-evals-listScores-request

Request example

{}

Guide request for Read judgments about that same reply. Replace example resource identifiers with your own authorized values.​

Section ID: DOC-IS-evaluation-api-listScores#example-cookbook-insights-evaluation-reading-03-request

Request example

{
  "conversationId": "conv_123",
  "dataType": "SCORE_DATA_TYPE_NUMERIC",
  "pageSize": 50
}

Illustrative response shape; omitted default fields and actual outcomes depend on the operation.​

Section ID: DOC-IS-evaluation-api-listScores#example-evals-listScores-response

Response example

{
  "scores": [
    {
      "scoreId": "example_123",
      "targetType": "EVAL_TARGET_TYPE_TRACE",
      "targetId": "example_123",
      "name": "example",
      "dataType": "SCORE_DATA_TYPE_NUMERIC",
      "numericValue": 1,
      "stringValue": "example",
      "booleanValue": true,
      "source": "SCORE_SOURCE_JUDGE",
      "comment": "example",
      "createdAt": "2026-09-16T12:00:00Z",
      "textValue": "Example text",
      "authorUserId": "example_123",
      "configId": "example_123",
      "queueId": "example_123",
      "traceId": "example_123",
      "observationId": "example_123",
      "sessionId": "example_123",
      "datasetRunId": "example_123",
      "environment": "example",
      "metadataJson": "{}",
      "updatedAt": "2026-09-16T12:00:00Z",
      "timestamp": "2026-09-16T12:00:00Z",
      "traceName": "example",
      "userId": "example_123",
      "sourceLabel": "example",
      "conversationId": "example_123",
      "messageId": "example_123",
      "messageSequence": "1",
      "profileId": "example_123",
      "configHash": "example"
    }
  ],
  "filterNarrowed": true,
  "cursorPage": {
    "nextCursor": "example",
    "limit": 1,
    "totalItems": 1
  }
}

Illustrative response for Read judgments about that same reply. Replace example resource identifiers with your own authorized values.​

Section ID: DOC-IS-evaluation-api-listScores#example-cookbook-insights-evaluation-reading-json-01-response

Response example

{
  "scores": [
    {
      "scoreId": "scr_7788",
      "name": "helpfulness",
      "dataType": "SCORE_DATA_TYPE_NUMERIC",
      "numericValue": 4,
      "source": "SCORE_SOURCE_HUMAN",
      "authorUserId": "reviewer_9",
      "configId": "cfg_help",
      "traceId": "trc_a1b2c3",
      "createdAt": "2026-08-12T16:20:00Z",
      "comment": "Answered, but buried the actual number."
    }
  ],
  "cursorPage": {
    "limit": 50
  },
  "filterNarrowed": true
}

Document ID: DOC-IS-evaluation-api-listScores. Section identities and revisions.

SectionStable reference
List scoresDOC-IS-evaluation-api-listScores#overview
RequestDOC-IS-evaluation-api-listScores#request
ResponsesDOC-IS-evaluation-api-listScores#responses