Skip to main content
POST
Evaluate multiple sessions in one call

Authorizations

Authorization
string
header
required

API key authorization. Pass your API key in the Authorization header as a Bearer token. Both new (gsk_*) and legacy (gsk-) API keys are accepted, e.g. Authorization: Bearer gsk_... or Authorization: Bearer gsk-....

Body

application/json
sessionIds
string[] | null

Explicit list of session IDs to evaluate. Mutually exclusive with versionId.

Example:
versionId
string | null

Evaluate every session attached to this version. Mutually exclusive with sessionIds.

Example:

"ver_123"

metrics
object[] | null

Metrics to evaluate. When provided, these exact metrics are applied to every session and per-specification scoping is bypassed. Optional: if omitted, each session is scored by the metrics of its own originating specification.

specificationIds
string[] | null

Specification IDs used to scope evaluation. If metrics is omitted, a session whose own specification is in the list is evaluated with that specification's linked metrics, and a session whose own specification is not in the list is skipped. A session with no specification of its own (for example an imported one) is evaluated with the linked metrics of the listed specifications of its own product, each metric once, and is skipped when there are none. If metrics is also provided, the explicit metrics apply to every session and these specs' metrics are merged in (additive), with no per-session scoping.

Response

Batch evaluation processed

sessionsEvaluated
integer
required

Number of sessions whose evaluations were dispatched successfully. Sessions skipped during per-specification scoping are counted in neither this nor sessionsFailed.

sessionsFailed
integer
required

Number of sessions whose evaluation failed.

evaluationsCreated
integer
required

Total number of Evaluation records created across all successful sessions.

failures
object[]
required

Per-session failure details.

message
string
required

Human-readable summary. Reports how many sessions were evaluated, failed, and skipped during per-specification scoping, naming each skip cause with its own count and reason, plus any truncation note.

totalSessionsAvailable
integer | null
required

Total sessions matching the request (versionId mode only). When greater than the count actually evaluated the response was truncated to the first 1000 rows. null in sessionIds mode.

truncated
boolean
required

True when the version had more sessions than the per-request page limit (1000).

runIds
string[]
required

The runs this launch is attributed to, one per product the sessions belong to.