Bayes Scoring with Strand-Level Results

This article describes the strand-level scoring endpoint for the Bayes Scoring Service. This endpoint combines a student's prior assessment history with new item results to produce an updated overall ability score and a breakdown of performance by individual skill areas (strands) — in a single API call.

What Changed

Previously, retrieving strand-level performance required making a Bayes scoring call and then applying a separate conversion table to map results into skill-area measures and performance bands. This endpoint handles that process automatically and returns strand scores directly in the response.

The Bayes scoring method is recommended when a prior ability score is available for the student, as it produces a more precise estimate by taking into account both the student's history and the time elapsed since their last assessment.

URL

POST /api/score/items/idsWithResults/bayes/strands

Request

In addition to the standard fields for grade, time of year, and items, the Bayes strand call requires three fields that describe the student's prior assessment. An example is provided below.

Parameter Type Description
priorAbility integer Required. The student's ability score from their most recent previous assessment.
priorUncertainty integer Required. The confidence range (uncertainty) associated with that prior score.
elapsedDays integer Required. The number of days that have passed since the prior assessment was taken.
grade integer Required. The student's grade level (e.g. 0 for Kindergarten, 3 for Grade 3).
timeOfYear string Required. The point in the school year. Accepted values: BOY (Beginning), MOY (Middle), EOY (End).
items array Required. A list of assessment items the student responded to.
items[].id string Required. The unique identifier for the item (e.g. "Q1234").
items[].result integer Required. The student's response result for that item.

Example request:

{
                "priorAbility": 100,
                "priorUncertainty": 200,
                "elapsedDays": 45,
                "grade": 3,
                "timeOfYear": "MOY",
                "items": [
                { "id": "Q1234", "result": 1 },
                { "id": "Q1235", "result": 0 }
                ]
                }

Response

A successful response (HTTP 200) returns an updated overall ability score that incorporates both the prior history and the new assessment, plus a strands array containing one entry per skill area assessed.

Parameter Type Description
ability integer The student's updated overall ability score.
abilityDisplay string A display-ready version of the ability score with all standard formatting rules applied, including rounding, caps, and framework label (e.g. "320L" or "BR200L"). Use this value when presenting scores in user interfaces or reports.
uncertainty integer The confidence range around the updated ability score.
framework string The scoring framework used (e.g. "lexile").
apiVersion string The build version of the API that processed the request.
strands array A list of strand-level scores. See fields below.
strands[].name string The name of the skill strand (e.g. "Phonics").
strands[].ability integer The student's ability score for this strand.
strands[].abilityDisplay string A display-ready version of the strand ability score.
strands[].uncertainty integer The confidence range for this strand score.
strands[].category integer A numeric value representing the student's performance band for this strand. See the Performance Band Reference for category definitions.

Example response:

{
                "ability": 320,
                "abilityDisplay": "320L",
                "uncertainty": 288,
                "framework": "lexile",
                "apiVersion": "ecf08905-main",
                "strands": [
                {
                "name": "Phonics",
                "ability": 320,
                "abilityDisplay": "320L",
                "uncertainty": 288,
                "category": 3
                }
                ]
                }

Error Responses

HTTP Code Meaning What to Check
400 Invalid input Check that all required fields are present, including priorAbility, priorUncertainty, and elapsedDays. The response body will include specific validation errors.
401 Unauthorized Your credentials could not be verified. Check that you are sending a valid authentication token.
403 Forbidden Your account does not have the required permissions to use this endpoint. Contact your account manager if you believe this is an error.

Related Resources