Create alignment run
Scores how closely one evaluator versionās labels matched the human annotations on a dataset version, using the column pair and comparison function named by the alignment task in the path.
Scoring is synchronous: the score is computed before the response is
returned, so the created run already carries its score and
comparable_row_count. There is no run to poll for.
A run that could not be scored still returns 201. The run resource was
created, so it is returned with status: FAILED and a public
failed_reason. Backend error details are kept in server logs.
A failed score is not a server error and is not reported as 5xx. Check
status on every response rather than relying on the status code alone.
Read score and comparable_row_count together. score is null, not
0, when no row had both a judge label and a human annotation: nothing was
comparable, so no agreement was measured. A score of 0 means rows were
compared and none agreed. A high score over a small
comparable_row_count is not a meaningful result.
A finished run is never rewritten. Scoring the same version again creates another run, because both the annotations and the taskās columns can change between scores.
Payload Requirements
evaluator_version_idis required: the evaluator version to score. The caller must have update access to the evaluator that owns it.dataset_version_idis required and must belong to the alignment taskās dataset. A dataset version from another dataset returns404, the same as one that does not exist.predicted_entityis required and names what produced the judge labels:entity_type: DATASET_VERSIONwhen the labels were already on the dataset, orentity_type: EXPERIMENTwhen an experiment produced them. An entity that does not belong to the same dataset returns404.- System-managed fields (
id,created_at,updated_at,status,score,comparable_row_count,failed_reason) are rejected on input.alignment_task_idis taken from the path and is rejected in the body.
The response records predicted_entity on successful and failed runs.
Malformed IDs, incorrect field types, and a body that is not an object
return 400. Missing required values, unsupported entity types, and
unknown fields return 422.
Valid example
{
"evaluator_version_id": "RXZhbHVhdG9yVmVyc2lvbjoxMDpYeVp3",
"dataset_version_id": "RGF0YXNldFZlcnNpb246NTY6UXJTdA==",
"predicted_entity": {
"id": "RGF0YXNldFZlcnNpb246NTY6UXJTdA==",
"entity_type": "DATASET_VERSION"
}
}
Invalid example (score is computed by the server and cannot be supplied)
{
"evaluator_version_id": "RXZhbHVhdG9yVmVyc2lvbjoxMDpYeVp3",
"dataset_version_id": "RGF0YXNldFZlcnNpb246NTY6UXJTdA==",
"predicted_entity": {
"id": "RGF0YXNldFZlcnNpb246NTY6UXJTdA==",
"entity_type": "DATASET_VERSION"
},
"score": 0.9
}
Authorizations
Most Arize AI endpoints require authentication. For those endpoints that require authentication, include your API key in the request header using the format
Service accounts may instead present an access token issued by an external identity provider (Microsoft Entra ID) when the account admin has configured that provider. Send it in the same header: Authorization: Bearer <access-token>.
Path Parameters
Body
Body containing alignment run parameters.
Body containing alignment run parameters.
Response
Returns the created alignment run
One alignment score: how closely an evaluator version's labels matched the human annotations over one dataset version, using the column pair and function its task names. A finished run is never rewritten -- re-scoring creates a new run.
The fraction of comparable rows on which the evaluator's label and the human annotation agreed, from 0 to 1.
null means no row had both a judge label and a human annotation, so
there was nothing to compare. null is not the same as 0: 0 means
rows were compared and none of them agreed. Treating null as 0
reports total disagreement where nothing was measured at all.
Always null when status is FAILED.
0 <= x <= 1How many rows had both a judge label and a human annotation. This is the
denominator score was computed over, so a high score over a small
comparable_row_count is not meaningful -- read the two together.
null when the count is unknown, which includes every FAILED run. A
value of 0 pairs with a null score.
x >= 0Was this page helpful?