Scores API

Scores attach evaluation results to traces or observations. They can be created programmatically (via API or SDK), from human annotation, or from automated evaluators.

Create Score

POST /api/public/scores

Authentication: Accepts write-only keys.

Request Body

Field	Type	Required	Description
`id`	`string`	No	Score ID (auto-generated if omitted)
`traceId`	`string`	Yes	ID of the trace to score
`name`	`string`	Yes	Score name (e.g., `"correctness"`, `"faithfulness"`)
`value`	`number`	Yes (NUMERIC/BOOLEAN)	Numeric score value
`stringValue`	`string`	Yes (CATEGORICAL)	Categorical value
`dataType`	`string`	No	`NUMERIC`, `BOOLEAN`, `CATEGORICAL` (default: `NUMERIC`)
`observationId`	`string`	No	ID of the observation to attach to (optional)
`comment`	`string`	No	Human-readable comment
`configId`	`string`	No	Score config ID for constrained scoring
`environment`	`string`	No	Environment name

Response

{ "id": "score-uuid-1" }

cURL Examples

Numeric score:

curl -X POST https://evals-api.browserstack.com/api/public/scores \
  -u "pk-lf-...:sk-lf-..." \
  -H "Content-Type: application/json" \
  -d '{
    "traceId": "trace-uuid-1",
    "name": "correctness",
    "value": 0.92,
    "comment": "Answer is accurate and well-referenced."
  }'

Categorical score:

curl -X POST https://evals-api.browserstack.com/api/public/scores \
  -u "pk-lf-...:sk-lf-..." \
  -H "Content-Type: application/json" \
  -d '{
    "traceId": "trace-uuid-1",
    "name": "quality",
    "dataType": "CATEGORICAL",
    "stringValue": "good"
  }'

Boolean score on a specific observation:

curl -X POST https://evals-api.browserstack.com/api/public/scores \
  -u "pk-lf-...:sk-lf-..." \
  -H "Content-Type: application/json" \
  -d '{
    "traceId": "trace-uuid-1",
    "observationId": "obs-uuid-1",
    "name": "factual",
    "dataType": "BOOLEAN",
    "value": 1
  }'

List Scores

GET /api/public/scores

Query Parameters

Parameter	Type	Description
`page`	`integer`	Page number (default: `1`)
`limit`	`integer`	Items per page (default: `50`)
`name`	`string`	Filter by score name
`userId`	`string`	Filter by user ID
`traceId`	`string`	Filter by trace ID
`source`	`string`	Filter by source: `API`, `EVAL`, `ANNOTATION`
`dataType`	`string`	Filter by data type: `NUMERIC`, `BOOLEAN`, `CATEGORICAL`
`configId`	`string`	Filter by score config ID
`queueId`	`string`	Filter by annotation queue ID
`traceTags`	`string[]`	Filter by tags on the parent trace
`environment`	`string`	Filter by environment
`fromTimestamp`	`ISO 8601`	Created at or after
`toTimestamp`	`ISO 8601`	Created at or before
`scoreIds`	`string[]`	Filter by specific score IDs
`value`	`number`	Filter by exact numeric value
`operator`	`string`	Comparison for value: `=`, `<`, `>`, `<=`, `>=`

Response

{
  "data": [
    {
      "id": "score-uuid-1",
      "traceId": "trace-uuid-1",
      "observationId": null,
      "name": "correctness",
      "value": 0.92,
      "stringValue": null,
      "dataType": "NUMERIC",
      "source": "API",
      "comment": "Answer is accurate.",
      "configId": null,
      "environment": "default",
      "createdAt": "2026-04-03T10:05:00.000Z",
      "updatedAt": "2026-04-03T10:05:00.000Z"
    }
  ],
  "meta": {
    "page": 1,
    "limit": 50,
    "totalItems": 1,
    "totalPages": 1
  }
}

cURL Example

curl "https://evals-api.browserstack.com/api/public/scores?name=correctness&page=1&limit=20" \
  -u "pk-lf-...:sk-lf-..."

Get Score

GET /api/public/scores/{scoreId}

Path Parameters

Parameter	Type	Description
`scoreId`	`string`	Score ID

Response

Same schema as list response items.

cURL Example

curl "https://evals-api.browserstack.com/api/public/scores/score-uuid-1" \
  -u "pk-lf-...:sk-lf-..."

Delete Score

DELETE /api/public/scores/{scoreId}

Path Parameters

Parameter	Type	Description
`scoreId`	`string`	Score ID

cURL Example

curl -X DELETE "https://evals-api.browserstack.com/api/public/scores/score-uuid-1" \
  -u "pk-lf-...:sk-lf-..."

Score Configs

Score configs define named, constrained score dimensions (e.g., a 1–5 rating scale).

List Score Configs

GET /api/public/score-configs

curl "https://evals-api.browserstack.com/api/public/score-configs" \
  -u "pk-lf-...:sk-lf-..."

Get Score Config

GET /api/public/score-configs/{configId}

curl "https://evals-api.browserstack.com/api/public/score-configs/config-uuid-1" \
  -u "pk-lf-...:sk-lf-..."

Score Data Types

`dataType`	`value` field	`stringValue` field	Description
`NUMERIC`	Required (float)	—	Numeric score (e.g., 0.0–1.0)
`BOOLEAN`	Required (`0` or `1`)	—	Pass/fail score
`CATEGORICAL`	—	Required	Text label (e.g., `"good"`, `"bad"`)

Score Sources

`source`	Description
`API`	Created via REST API or SDK
`EVAL`	Created by an automated evaluator
`ANNOTATION`	Created by a human via the annotation queue

Scores API

On this page