Alpha surface
Use this API when a Learning Report needs active, inactive, or waste time, minutes per enrolled school day, XP totals, mastery deltas, MAP RIT and Growth X, or progress evidence. Reports read Analytics rows for evidence and use Results course-progress / grade-level-progress for the app-facing progress answer. They do not rebuild platform math from Events, Results, Curriculum, calendars, or source exports.
Quickstart
The docs-hosted demo API implements the approved customer contract with representative rows. The implementation deliverable must publish the same endpoint shapes at https://platform3-andymontgomery-9773s-projects.vercel.app/analytics/alpha/implementation/api.
export ANALYTICS_BASE_URL="https://platform3-andymontgomery-9773s-projects.vercel.app/analytics/alpha/customer_website/api"curl -sS -X POST "$ANALYTICS_BASE_URL/dev/mint?tenantId=demo"
export ANALYTICS_TOKEN="$(curl -sS -X POST "$ANALYTICS_BASE_URL/dev/mint?tenantId=demo" | node -pe 'JSON.parse(fs.readFileSync(0,"utf8")).token')"curl -sS "$ANALYTICS_BASE_URL/alpha/analytics/v1/school-day-minutes?studentId=student_01HT7G3YZV7QB5N4YKQ1K0Z9A9&subjectId=math&startDate=2026-05-01&endDate=2026-06-01&includeUnavailable=true" \
-H "Authorization: Bearer $ANALYTICS_TOKEN"null_reason=source_missing or policy_pending, render that typed status. Do not substitute app-side calendar math, XP constants, or source-table queries.Boundary
Analytics owns these measures and reference translations. A Learning Report client renders the returned fields and provenance; it does not keep a second copy of the platform in app code.
Trace: aitd-000-extend-only-storage aitd-001-report-source-ingestion aitd-015-norms-r90-readable-resources aitd-016-scale-translation-apis
Recipe
Call the report-ready collections below. Each row carries the policy/version/source refs needed to audit the number later.
API path: /alpha/analytics/v1/school-day-minutes, /alpha/analytics/v1/time-windows
Raw DB path: Read alpha.analytics_school_day_minutes and alpha.analytics_time_window at the documented grain. Keep source_missing or policy_pending rows visible when includeUnavailable=true. Do not count school days in the client.
API path: /alpha/analytics/v1/xp-rollups
Raw DB path: Read alpha.analytics_xp_rollup. Do not SUM reporting.processed_facts, cap goal percent, or reconstruct policy rows in the report client.
API path: /alpha/analytics/v1/accuracy-rollups
Raw DB path: Read alpha.analytics_accuracy for correct questions, total questions, incorrect questions, and accuracy percent. Do not divide reporting.processed_facts in the report client.
API path: /alpha/analytics/v1/mastery-deltas
Raw DB path: Read alpha.analytics_mastery_delta for changes in the window. Current mastery state remains a Results object; the report does not recompute mastery.
API path: /alpha/analytics/v1/map-growth-rollups
Raw DB path: Read alpha.analytics_map_growth_rollup by canonical_term_id, growth_window, and norms_set. Do not parse NWEA terms, choose retakes, or compute Growth X.
API path: /alpha/analytics/v1/norms, /alpha/analytics/v1/norms/table, /alpha/analytics/v1/norms/rit, /alpha/analytics/v1/norms/percentile, /alpha/analytics/v1/r90/table, /alpha/analytics/v1/r90, /alpha/analytics/v1/school-days-remaining, /alpha/analytics/v1/grade-level-status
Raw DB path: Read alpha.analytics_norms_achievement and alpha.analytics_r90_table by norms_set/current version and exact requested RIT. For remaining school days, read alpha.school_calendar under alpha.policy.school_day over the documented half-open [asOf, endDate) window. Never ship a private norms/R90 table or a private school-day calendar.
API path: /alpha/analytics/v1/completion-rollups
Raw DB path: Read alpha.analytics_completion_rollup by completion_scope and scope_id. Course rows prefer app-reported Caliper percent, then XP remaining; grade_level rows average main-course rows only. Do not derive actual progress from MAP/RIT/R90 or count Results client-side.
const base = process.env.ANALYTICS_BASE_URL;
const studentId = "student_01HT7G3YZV7QB5N4YKQ1K0Z9A9";
let token = process.env.ANALYTICS_TOKEN || await mintDemoToken();
async function mintDemoToken() {
const response = await fetch(`${base}/dev/mint?tenantId=demo`, { method: "POST" });
if (!response.ok) throw await response.json();
return (await response.json()).token;
}
async function analyticsJson(url, retriedAuth = false) {
const response = await fetch(url, { headers: { Authorization: `Bearer ${token}` } });
if (response.ok) return response.json();
const problem = await response.json();
const fieldCodes = new Set((problem.fieldErrors || []).map((item) => item.code));
if (response.status === 401 && !retriedAuth) {
// Missing, malformed, invalid, or expired bearer token. The rejected request did not run.
token = await mintDemoToken();
return analyticsJson(url, true);
}
if (response.status === 403) {
throw new Error(`Abort credential path: ${problem.detail}. Get analytics:read for this tenant/student grant.`);
}
if (problem.code === "analytics:source_missing") {
throw new Error(`Retry only after source repair or replay: ${problem.detail}`);
}
if (problem.code === "analytics:validation_failed" || problem.code === "analytics:unsupported_parameter") {
throw new Error(`Abort and fix request shape: ${problem.detail}; field codes=${[...fieldCodes].join(",")}`);
}
throw problem;
}
async function readAllPages(path, checkpoint) {
let cursor;
let maxModifiedAt = checkpoint;
do {
const url = new URL(base + path);
if (cursor) url.searchParams.set("cursor", cursor);
if (!cursor && checkpoint) url.searchParams.set("modifiedSince", checkpoint);
const page = await analyticsJson(url);
render(page.data);
for (const row of page.data || []) {
if (row.modified_at && (!maxModifiedAt || row.modified_at > maxModifiedAt)) {
maxModifiedAt = row.modified_at;
}
}
cursor = page.nextCursor;
} while (cursor);
// Persist only after the entire page walk succeeds. 401 retries reuse the same URL.
saveCheckpoint(path, maxModifiedAt);
}
const common = new URLSearchParams({ studentId, startDate: "2026-05-01", endDate: "2026-06-01", limit: "100" });
for (const path of [
"/alpha/analytics/v1/school-day-minutes?" + common + "&includeUnavailable=true",
"/alpha/analytics/v1/xp-rollups?" + common + "&windowKind=term",
"/alpha/analytics/v1/accuracy-rollups?" + common + "&windowKind=term",
"/alpha/analytics/v1/mastery-deltas?" + common,
"/alpha/analytics/v1/map-growth-rollups?studentId=" + studentId + "&termId=term_2026_winter&growthWindow=winter_to_winter&normsSet=2025",
"/alpha/analytics/v1/completion-rollups?studentId=" + studentId + "&completionScope=course"
]) {
await readAllPages(path, loadCheckpoint(path));
}GOALS recipe
GOALS asks Analytics for the versioned reference tables and calculators to turn a percentile target into RIT, then R90 grade position, then actual grade-level progress and remaining school-day pacing. The current R90 selector is analytics.rit_to_grade.powerpath.v2026-06-15 per AITD-017. The app may cache the returned tables by table_version, but apps never maintain their own norms/R90 tables, carry a private norms or R90 copy, infer the current table by sorting version names, derive actual progress from MAP/RIT/R90, or count instructional days locally.
curl -sS "$ANALYTICS_BASE_URL/alpha/analytics/v1/norms?subject=math&grade=5&season=winter&normsSet=2025&limit=1" \
-H "Authorization: Bearer $ANALYTICS_TOKEN"{
"object": "list",
"table": "analytics.norms_table",
"table_version": "analytics.norms.achievement.v2026-06-12",
"data": [
{
"id": "norms_2025_math_student_5_winter",
"norms_set": "2025",
"subject_id": "math",
"source_subject_name": "Math",
"role": "student",
"grade_key": "5",
"grade_level": 5,
"season": "winter",
"mean_rit": 211.82,
"sd_rit": 17.42,
"calculator_version": "analytics.norms.achievement.v2026-06-12",
"source_ref": "NWEA 2025 MAP Growth Norms Technical Manual (Hawthorne, Velazquez, Peng, Hall, Newburn, 2025)"
}
],
"limit": 1,
"hasMore": false,
"nextCursor": null,
"links": {
"self": "/alpha/analytics/v1/norms?subject=math&grade=5&season=winter&normsSet=2025&limit=1"
}
}/alpha/analytics/v1/norms/table
curl -sS "$ANALYTICS_BASE_URL/alpha/analytics/v1/norms/table?subject=math&grade=5&season=winter&normsSet=2025&limit=1" \
-H "Authorization: Bearer $ANALYTICS_TOKEN"{
"object": "list",
"table": "analytics.norms_table",
"table_version": "analytics.norms.achievement.v2026-06-12",
"data": [
{
"id": "norms_2025_math_student_5_winter",
"norms_set": "2025",
"subject_id": "math",
"source_subject_name": "Math",
"role": "student",
"grade_key": "5",
"grade_level": 5,
"season": "winter",
"mean_rit": 211.82,
"sd_rit": 17.42,
"calculator_version": "analytics.norms.achievement.v2026-06-12",
"source_ref": "NWEA 2025 MAP Growth Norms Technical Manual (Hawthorne, Velazquez, Peng, Hall, Newburn, 2025)"
}
],
"limit": 1,
"hasMore": false,
"nextCursor": null,
"links": {
"self": "/alpha/analytics/v1/norms/table?subject=math&grade=5&season=winter&normsSet=2025&limit=1"
}
}curl -sS "$ANALYTICS_BASE_URL/alpha/analytics/v1/norms/rit?subject=math&grade=5&season=winter&percentile=99&normsSet=2025" \
-H "Authorization: Bearer $ANALYTICS_TOKEN"{
"object": "analytics.norms_rit_translation",
"direction": "percentile_to_rit",
"norms_set": "2025",
"subject_id": "math",
"grade_key": "5",
"grade_level": 5,
"season": "winter",
"role": "student",
"percentile": 99,
"rit_score": 252,
"output_rit": 252,
"raw_rit": 252.345,
"calculator_version": "analytics.norms.achievement.v2026-06-12",
"mean_rit": 211.82,
"sd_rit": 17.42,
"source_ref": "NWEA 2025 MAP Growth Norms Technical Manual (Hawthorne, Velazquez, Peng, Hall, Newburn, 2025)",
"links": {
"table": "/alpha/analytics/v1/norms/table?subject=math&grade=5&season=winter&normsSet=2025&role=student"
}
}/alpha/analytics/v1/norms/percentile
curl -sS "$ANALYTICS_BASE_URL/alpha/analytics/v1/norms/percentile?subject=math&grade=5&season=winter&rit=247&normsSet=2025" \
-H "Authorization: Bearer $ANALYTICS_TOKEN"{
"object": "analytics.norms_percentile_translation",
"direction": "rit_to_percentile",
"norms_set": "2025",
"subject_id": "math",
"grade_key": "5",
"grade_level": 5,
"season": "winter",
"role": "student",
"rit_score": 247,
"input_rit": 247,
"percentile": 98,
"output_percentile": 98,
"raw_percentile": 97.828,
"calculator_version": "analytics.norms.achievement.v2026-06-12",
"mean_rit": 211.82,
"sd_rit": 17.42,
"source_ref": "NWEA 2025 MAP Growth Norms Technical Manual (Hawthorne, Velazquez, Peng, Hall, Newburn, 2025)",
"links": {
"table": "/alpha/analytics/v1/norms/table?subject=math&grade=5&season=winter&normsSet=2025&role=student"
}
}curl -sS "$ANALYTICS_BASE_URL/alpha/analytics/v1/r90/table?subject=math&normsSet=2025&limit=1" \
-H "Authorization: Bearer $ANALYTICS_TOKEN"{
"object": "list",
"table": "analytics.r90_table",
"table_version": "analytics.rit_to_grade.powerpath.v2026-06-15",
"data": [
{
"id": "r90_math_172",
"table_version": "analytics.rit_to_grade.powerpath.v2026-06-15",
"table_subject_id": "math",
"subject_id": "math",
"source_subject_name": "Math",
"rit_score": 172,
"r90_grade": 0,
"effective_grade": 1,
"r90_grade_level": 0,
"r90_percent_complete": 0,
"rit90_grade_band_percent": 0,
"observation_count": 1,
"source_ref": "powerpath:/powerpath/rit-to-grade",
"ownerModule": "nweamap"
}
],
"limit": 1,
"hasMore": true,
"nextCursor": "eyJvZmZzZXQiOjF9",
"links": {
"self": "/alpha/analytics/v1/r90/table?subject=math&normsSet=2025&limit=1"
}
}curl -sS "$ANALYTICS_BASE_URL/alpha/analytics/v1/r90?subject=math&rit=239&normsSet=2025" \
-H "Authorization: Bearer $ANALYTICS_TOKEN"{
"object": "analytics.r90_lookup",
"table_version": "analytics.rit_to_grade.powerpath.v2026-06-15",
"requested_subject_id": "math",
"table_subject_id": "math",
"subject_id": "math",
"rit_score": 239,
"table_rit_score": 239,
"r90_grade": 4.8,
"effective_grade": 5,
"r90_grade_level": 4,
"r90_percent_complete": 80,
"rit90_grade_band_percent": 80,
"source_point_kind": "exact",
"calculator_version": "analytics.rit_to_grade.powerpath.v2026-06-15",
"source_ref": "powerpath:/powerpath/rit-to-grade",
"ownerModule": "nweamap",
"links": {
"table": "/alpha/analytics/v1/r90/table?subject=math"
}
}/alpha/analytics/v1/school-days-remaining
curl -sS "$ANALYTICS_BASE_URL/alpha/analytics/v1/school-days-remaining?studentId=student-ada-001&asOf=2026-06-14&endDate=2026-07-24&xpRemaining=600&hoursPerSchoolDay=1.5&targetDate=2026-07-24" \
-H "Authorization: Bearer $ANALYTICS_TOKEN"{
"object": "analytics.school_days_remaining",
"student_id": "student-ada-001",
"school_id": "school_alpha_demo",
"as_of": "2026-06-14",
"end_date": "2026-07-24",
"school_day_policy_ref": "alpha.policy.school_day.v2026-06-10",
"instructional_days_remaining": 29,
"calendar_ref_count": 40,
"first_instructional_date": "2026-06-15",
"last_instructional_date": "2026-07-23",
"instructional_dates": [
"2026-06-15",
"2026-06-16",
"2026-06-17"
],
"xp_unit": {
"policy_ref": "alpha.policy.analytics.xp_expected_minute.v2026-06-14",
"xp_per_expected_minute": 1,
"xp_per_hour": 60,
"meaning": "1 XP = 1 expected minute; XP hours = XP / 60."
},
"effort": {
"xp_remaining": 600,
"expected_minutes_remaining": 600,
"hours_remaining": 10,
"target_date": "2026-07-24",
"school_days_until_target_date": 29,
"required_hours_per_school_day_to_target_date": 0.345,
"hours_per_school_day": 1.5,
"school_days_needed_at_hours_per_school_day": 7,
"target_date_at_hours_per_school_day": "2026-06-23",
"can_finish_by_end_date_at_hours_per_school_day": true
},
"provenance": {
"source": "alpha.school_calendar",
"source_ref_sample": [
"ed_fi.CalendarDate:school_alpha_demo:2026-06-15"
],
"policy_ref": "alpha.policy.school_day.v2026-06-10",
"xp_unit_policy_ref": "alpha.policy.analytics.xp_expected_minute.v2026-06-14"
},
"links": {
"self": "/alpha/analytics/v1/school-days-remaining?studentId=student-ada-001&asOf=2026-06-14&endDate=2026-07-24",
"schoolDayMinutes": "/alpha/analytics/v1/school-day-minutes?studentId=student-ada-001",
"xpRollups": "/alpha/analytics/v1/xp-rollups?studentId=student-ada-001&windowKind=school_year"
}
}/alpha/analytics/v1/grade-level-status
curl -sS "$ANALYTICS_BASE_URL/alpha/analytics/v1/grade-level-status?studentId=b6fa7128-f641-4efd-9075-375411fd6c39&subject=math&asOfDate=2026-05-20" \
-H "Authorization: Bearer $ANALYTICS_TOKEN"{
"object": "analytics.grade_level_status",
"student_id": "b6fa7128-f641-4efd-9075-375411fd6c39",
"subject_id": "math",
"as_of_date": "2026-05-20",
"age_grade": 5,
"working_grade": 6,
"highest_mastered_grade": 5,
"working_age_grade_delta": 1,
"working_age_grade_status": "working_above_age_grade",
"mastered_age_grade_delta": 0,
"mastered_age_grade_status": "mastered_at_age_grade",
"source_refs": {
"age_grade": "people_and_orgs.alpha.age_grade_history",
"working_grade": "results.student_track_state.working_grade",
"highest_mastered_grade": "results.highest_mastered_grade"
},
"deprecated_aliases": {
"instructional_level_status": "working_age_grade_status",
"strict_mastery_status": "mastered_age_grade_status"
}
}output_rit, rit_score, r90_grade, effective_grade, r90_grade_level, rit90_grade_band_percent, completion_percent from completion_scope=grade_level, table_version, calculator_version, instructional_days_remaining, and effort.*. It does not interpolate norms, extrapolate R90, derive progress from MAP/RIT/R90, switch tables locally, count school days, or carry an XP-hours constant.Trace: aitd-015-norms-r90-readable-resources aitd-016-scale-translation-apis aitd-017-r90-version-supersession aitd-018-goals-school-days-remaining aitd-112-axis-list-endpoints
Runtime
Every non-demo endpoint requires Authorization: Bearer <token>.
Do not send tenantId in a query string or body. Tenant routing comes from the JWT claim.
Read endpoints require analytics:read. Source imports require analytics:write.
This is the complete 401/403 contract for long-running polling clients. Analytics inherits the shared Platform status meanings, while the response body uses the approved analytics:validation_failed carrier code. Do not collapse these into generic validation failures: branch on status and fieldErrors[].code.
| Status | Problem code | When it appears | Client action | Field-error codes | Trace |
|---|---|---|---|---|---|
401 Unauthorized |
analytics:validation_failed |
The Authorization header is missing, not a compact JWT, has an invalid signature or payload, or the token is expired. | Mint or refresh the token, then retry the exact same request. For polling clients, keep the last completed modifiedSince checkpoint; the rejected request did not run. | headers.Authorization code=requiredheaders.Authorization code=invalid_jwtheaders.Authorization code=invalid_signatureheaders.Authorization code=invalid_payloadheaders.Authorization code=expired |
Analytics Problem Platform 401 status |
403 Forbidden |
analytics:validation_failed |
The token is valid, but it has no tenantId claim, the x-timeback-tenant header does not match the token tenant, or the token lacks the required Analytics read/write authority. | Abort under the current token. Use a token with analytics:read for GET endpoints, analytics:write or analytics:import for source imports, and the correct student/cohort/tenant grant. | jwt.tenantId code=requiredheaders.x-timeback-tenant code=tenant_mismatchjwt.scopes code=missing_scope required=analytics:readjwt.scopes code=missing_scope required=analytics:write |
Analytics Problem Platform 403 status |
Trace: aitd-106-axis-auth-shape aitd-109-axis-tenant-routing
Runtime
| Item | Client contract |
|---|---|
| Envelope | Every GET list endpoint returns data, hasMore, nextCursor, and links.self. |
| Page size | limit defaults to 100 and has a maximum of 1000. Invalid limits return analytics:validation_failed. |
| Cursor | cursor is opaque and bound to tenant, endpoint, typed filters, and sort. Use it only to finish the active page walk. |
| Sort order | modifiedSince page walks order by modified_at then stable id. |
| Checkpoint | Persist modifiedSince only after a complete page walk. If interrupted, restart from the last complete checkpoint. |
| Item | Client contract |
|---|---|
| Parameter | modifiedSince is a UTC ISO-8601 timestamp over modified_at. |
| Source missing | analytics:source_missing means the source Event, Result, calendar, enrollment, Curriculum row, or source import was not available for materialization. Repair or wait for the source and replay; do not fill the gap from source modules. |
| Freshness model | Poll plus modifiedSince is the shipped eventing model. Webhooks are deferred. |
| Clock rule | Use server-returned modified_at values for checkpoints, never the client clock. |
| Item | Client contract |
|---|---|
| 401 Unauthorized (analytics:validation_failed) | Authentication branch: missing, malformed, invalid-signature, invalid-payload, or expired Bearer token. Mint or refresh the token, retry the exact request, and do not advance a modifiedSince checkpoint until a 2xx page succeeds. |
| 403 Forbidden (analytics:validation_failed) | Authorization branch: valid token but missing tenant, mismatched x-timeback-tenant, or missing analytics:read/write authority. Abort this credential path or obtain a token with the right scope/student/cohort grant; do not keep retrying. |
| 400 analytics:validation_failed | Abort and correct the request shape or enum value. |
| 400 analytics:unsupported_parameter | Abort and use only the endpoint's typed filters. |
| 409 analytics:source_missing | Retry only after the source close/import/calendar prerequisite changes. Keep filters stable and use modifiedSince for sync. |
| 409 analytics:idempotency_conflict | Abort the replay or reuse the exact original import body for that key. |
| 422 adapter/policy problems | Repair the source mapping or policy/config row, then replay. Do not hard-code the missing value in the client. |
| 500 analytics:schema_migration_failed | Operator fix only. Do not work around it by recomputing from source tables. |
| Item | Client contract |
|---|---|
| Tenant routing | Tenant comes from the JWT. The API never accepts tenantId in query or body. |
| Idempotency | Source imports require Idempotency-Key. Reads do not require it. |
| Retention | Current reads exclude superseded and source-deleted rows unless an authorized audit endpoint explicitly includes them. |
Trace: aitd-103-axis-query-model aitd-107-axis-eventing aitd-108-axis-error-envelope aitd-105-axis-idempotency
Runtime
Every error is a typed RFC 7807 Problem. The first two cards are the status-specific auth-failure contract. For Analytics-owned failures, classify by code. For auth failures, code remains analytics:validation_failed, and clients branch by status plus fieldErrors[].code. The documented examples match the docs-hosted demo handler and implementation envelope: type, title, status, code, detail, fieldErrors, requestId, and traceId.
401 Unauthorized analytics:validation_failedThe Authorization header is missing, not a compact JWT, has an invalid signature or payload, or the token is expired.
Client action: Mint or refresh the token, then retry the exact same request. For polling clients, keep the last completed modifiedSince checkpoint; the rejected request did not run.
Analytics validation Problem Inherited Platform 401 status aitd-106-axis-auth-shape aitd-108-axis-error-envelope
curl -i "$ANALYTICS_BASE_URL/alpha/analytics/v1/school-day-minutes?studentId=student_01HT7G3YZV7QB5N4YKQ1K0Z9A9&startDate=2026-05-01&endDate=2026-06-01"
# Fix: mint or refresh a token, then retry the same URL without advancing modifiedSince.{
"type": "https://platform3-andymontgomery-9773s-projects.vercel.app/analytics/alpha/data_dictionary#problem-analytics-validation-failed",
"title": "Bearer token is expired.",
"status": 401,
"code": "analytics:validation_failed",
"detail": "Bearer token is expired.",
"fieldErrors": [
{
"path": "headers.Authorization",
"code": "required"
},
{
"path": "headers.Authorization",
"code": "invalid_jwt"
}
],
"requestId": "req_01J0ANALYTICS",
"traceId": "trace_01J0ANALYTICS"
}403 Forbidden analytics:validation_failedThe token is valid, but it has no tenantId claim, the x-timeback-tenant header does not match the token tenant, or the token lacks the required Analytics read/write authority.
Client action: Abort under the current token. Use a token with analytics:read for GET endpoints, analytics:write or analytics:import for source imports, and the correct student/cohort/tenant grant.
Analytics validation Problem Inherited Platform 403 status aitd-106-axis-auth-shape aitd-108-axis-error-envelope
curl -i "$ANALYTICS_BASE_URL/alpha/analytics/v1/school-day-minutes?studentId=student_01HT7G3YZV7QB5N4YKQ1K0Z9A9&startDate=2026-05-01&endDate=2026-06-01" \
-H "Authorization: Bearer forbidden.demo.jwt"
# Fix: abort this credential path and obtain a token with analytics:read for the right tenant/student grant.{
"type": "https://platform3-andymontgomery-9773s-projects.vercel.app/analytics/alpha/data_dictionary#problem-analytics-validation-failed",
"title": "Analytics reads require analytics:read authority.",
"status": 403,
"code": "analytics:validation_failed",
"detail": "Analytics reads require analytics:read authority.",
"fieldErrors": [
{
"path": "jwt.tenantId",
"code": "required"
},
{
"path": "headers.x-timeback-tenant",
"code": "tenant_mismatch"
}
],
"requestId": "req_01J0ANALYTICS",
"traceId": "trace_01J0ANALYTICS"
}analytics:validation_failed 400The request envelope, query string, dates, enum values, or required fields are invalid before an adapter/materializer can run. Carries field-level codes, including the norms/R90 reference codes norms_subject_not_found, r90_subject_not_found, norms_point_not_found, r90_point_not_found (aitd-015/016). Also the status carrier for 401/403/404/405/415 envelope errors.
Client action: Correct the request shape or query parameter. Do not retry the same body under a new idempotency key.
Data dictionary Problem entry aitd-103-axis-query-model aitd-108-axis-error-envelope
{
"type": "https://platform3-andymontgomery-9773s-projects.vercel.app/analytics/alpha/data_dictionary#problem-analytics-validation-failed",
"title": "normsSet=2026, completionScope=course_component, window_end before window_start, or tenantId supplied in the query string.",
"status": 400,
"code": "analytics:validation_failed",
"detail": "normsSet=2026, completionScope=course_component, window_end before window_start, or tenantId supplied in the query string.",
"fieldErrors": [
{
"path": "query.normsSet",
"code": "invalid_enum"
}
],
"requestId": "req_01J0ANALYTICS",
"traceId": "trace_01J0ANALYTICS"
}analytics:unsupported_parameter 400A query parameter is not part of the typed query model (Vercel routing params such as path are stripped before validation).
Client action: Use only documented filters from the table grain and endpoint contract; strip routing params before validation.
Data dictionary Problem entry aitd-103-axis-query-model aitd-108-axis-error-envelope
{
"type": "https://platform3-andymontgomery-9773s-projects.vercel.app/analytics/alpha/data_dictionary#problem-analytics-unsupported-parameter",
"title": "Filtering completion-rollups by raw course_component_kind instead of completion_scope/scope_id.",
"status": 400,
"code": "analytics:unsupported_parameter",
"detail": "Filtering completion-rollups by raw course_component_kind instead of completion_scope/scope_id.",
"fieldErrors": [
{
"path": "query.course_component_kind",
"code": "unsupported"
}
],
"requestId": "req_01J0ANALYTICS",
"traceId": "trace_01J0ANALYTICS"
}analytics:adapter_rejected 422A valid source-shaped row cannot be normalized, OR an expected report-source row is missing — a reconciliation error, never a silent default.
Client action: Repair the source mapping or upstream row, then replay the same source-shaped row idempotently.
Data dictionary Problem entry aitd-001-report-source-ingestion aitd-011-policy-and-enum-normalization aitd-108-axis-error-envelope
{
"type": "https://platform3-andymontgomery-9773s-projects.vercel.app/analytics/alpha/data_dictionary#problem-analytics-adapter-rejected",
"title": "A processed_facts row names an unknown subject, or a completion row points at a course the Curriculum surface cannot resolve.",
"status": 422,
"code": "analytics:adapter_rejected",
"detail": "A processed_facts row names an unknown subject, or a completion row points at a course the Curriculum surface cannot resolve.",
"fieldErrors": [
{
"path": "body.rows[0].subject",
"code": "unknown_subject"
}
],
"requestId": "req_01J0ANALYTICS",
"traceId": "trace_01J0ANALYTICS"
}analytics:idempotency_conflict 409The same Idempotency-Key or source_fact_key was replayed with different content.
Client action: Use the original body for replay, or submit a correction through the correction/reversal pathway.
Data dictionary Problem entry aitd-105-axis-idempotency aitd-012-corrections-and-reversals
{
"type": "https://platform3-andymontgomery-9773s-projects.vercel.app/analytics/alpha/data_dictionary#problem-analytics-idempotency-conflict",
"title": "A migration replay keeps the same source_fact_key but changes active_seconds from 300 to 360.",
"status": 409,
"code": "analytics:idempotency_conflict",
"detail": "A migration replay keeps the same source_fact_key but changes active_seconds from 300 to 360.",
"fieldErrors": [
{
"path": "headers.Idempotency-Key",
"code": "body_mismatch"
}
],
"requestId": "req_01J0ANALYTICS",
"traceId": "trace_01J0ANALYTICS"
}analytics:schema_migration_failed 500An internal/migration failure the surface could not recover from — surfaced honestly as 500, never a lying 200.
Client action: Follow the endpoint contract and retry only after the documented input or source condition changes.
Data dictionary Problem entry aitd-108-axis-error-envelope
{
"type": "https://platform3-andymontgomery-9773s-projects.vercel.app/analytics/alpha/data_dictionary#problem-analytics-schema-migration-failed",
"title": "See the endpoint-specific Problem response.",
"status": 500,
"code": "analytics:schema_migration_failed",
"detail": "See the endpoint-specific Problem response.",
"fieldErrors": [],
"requestId": "req_01J0ANALYTICS",
"traceId": "trace_01J0ANALYTICS"
}analytics:source_missing 409Analytics expected an Event, Result, calendar, enrollment, or Curriculum source row, but it was not available or not closed.
Client action: Wait for the source close/import to finish or repair the upstream source row, then replay the affected source/window. For school-day minutes, the fix is to surface the upstream Alpha calendar source and replay the window.
Data dictionary Problem entry aitd-003-close-time-materialization aitd-111-axis-privacy-retention aitd-108-axis-error-envelope
{
"type": "https://platform3-andymontgomery-9773s-projects.vercel.app/analytics/alpha/data_dictionary#problem-analytics-source-missing",
"title": "A TimeSpentEvent close notification references an event id that Events has already tombstoned.",
"status": 409,
"code": "analytics:source_missing",
"detail": "A TimeSpentEvent close notification references an event id that Events has already tombstoned.",
"fieldErrors": [
{
"path": "source.event_id",
"code": "not_available"
}
],
"requestId": "req_01J0ANALYTICS",
"traceId": "trace_01J0ANALYTICS"
}analytics:source_unlinked 422The source row exists, but Analytics cannot link it to the required Alpha student, subject, KC, course, school calendar, or policy ref.
Client action: Fix the upstream id mapping or governed alias/policy row. Do not supply a caller-normalized replacement id just for this import.
Data dictionary Problem entry aitd-011-policy-and-enum-normalization aitd-001-report-source-ingestion aitd-108-axis-error-envelope
{
"type": "https://platform3-andymontgomery-9773s-projects.vercel.app/analytics/alpha/data_dictionary#problem-analytics-source-unlinked",
"title": "A processed_facts row has subject=Science-notqced and no accepted subject fold.",
"status": 422,
"code": "analytics:source_unlinked",
"detail": "A processed_facts row has subject=Science-notqced and no accepted subject fold.",
"fieldErrors": [
{
"path": "body.rows[0].studentid",
"code": "unresolved_student"
}
],
"requestId": "req_01J0ANALYTICS",
"traceId": "trace_01J0ANALYTICS"
}analytics:policy_pending 422A required alpha.policy.* row is missing, inactive for the effective date, or lacks a governed value needed to compute the fact.
Client action: Seed or activate the policy row and replay. Reports and skill packs must not hard-code the missing value.
Data dictionary Problem entry aitd-011-policy-and-enum-normalization aitd-108-axis-error-envelope
{
"type": "https://platform3-andymontgomery-9773s-projects.vercel.app/analytics/alpha/data_dictionary#problem-analytics-policy-pending",
"title": "alpha.policy.school_day has no reason mapping for a real Ed-Fi CalendarEventDescriptor.",
"status": 422,
"code": "analytics:policy_pending",
"detail": "alpha.policy.school_day has no reason mapping for a real Ed-Fi CalendarEventDescriptor.",
"fieldErrors": [
{
"path": "alpha.policy.school_day",
"code": "policy_missing"
}
],
"requestId": "req_01J0ANALYTICS",
"traceId": "trace_01J0ANALYTICS"
}Two first-class paths
The raw path reads Analytics tables documented in the data dictionary. It does not reproduce source-module materializers or hidden report logic.
API-only: GET /school-day-minutes and GET /time-windows
Raw DB plus dictionary: Read alpha.analytics_school_day_minutes and alpha.analytics_time_window at the documented grain. Keep source_missing or policy_pending rows visible when includeUnavailable=true. Do not count school days in the client.
API-only: GET /xp-rollups
Raw DB plus dictionary: Read alpha.analytics_xp_rollup. Do not SUM reporting.processed_facts, cap goal percent, or reconstruct policy rows in the report client.
API-only: GET /accuracy-rollups
Raw DB plus dictionary: Read alpha.analytics_accuracy for correct questions, total questions, incorrect questions, and accuracy percent. Do not divide reporting.processed_facts in the report client.
API-only: GET /mastery-deltas
Raw DB plus dictionary: Read alpha.analytics_mastery_delta for changes in the window. Current mastery state remains a Results object; the report does not recompute mastery.
API-only: GET /map-growth-rollups
Raw DB plus dictionary: Read alpha.analytics_map_growth_rollup by canonical_term_id, growth_window, and norms_set. Do not parse NWEA terms, choose retakes, or compute Growth X.
API-only: GET /norms, GET /norms/table, GET /norms/rit, GET /norms/percentile, GET /r90/table, GET /r90, and GET /school-days-remaining
Raw DB plus dictionary: Read alpha.analytics_norms_achievement and alpha.analytics_r90_table by norms_set/current version and exact requested RIT. For remaining school days, read alpha.school_calendar under alpha.policy.school_day over the documented half-open [asOf, endDate) window. Never ship a private norms/R90 table or a private school-day calendar.
API-only: GET /completion-rollups
Raw DB plus dictionary: Read alpha.analytics_completion_rollup by completion_scope and scope_id. Course rows prefer app-reported Caliper percent, then XP remaining; grade_level rows average main-course rows only. Do not derive actual progress from MAP/RIT/R90 or count Results client-side.
Question: Which rows belong to this tenant?
API-only rule: The API takes tenant_id only from the JWT claim; tenantId in URL/query/body is rejected or ignored according to the endpoint contract.
Raw DB plus dictionary rule: Every raw query must filter alpha.analytics_* by tenant_id before joins, windows, counts, sorting, or paging.
Failure mode: A raw report mixes demo/reviewer/production tenants and returns plausible but wrong totals.
Question: How should a report answer a metric question?
API-only rule: Reports call the named Analytics endpoint for the metric.
Raw DB plus dictionary rule: Raw readers query the matching alpha.analytics_* table. They do not recompute from Events, Results, processed_facts, Curriculum trees, calendars, or private norms/R90 tables; for scale questions they read alpha.analytics_norms_achievement and the alpha.analytics_r90_table mirror sourced from the NWEAMAP-owned PowerPath RIT-to-grade master.
Failure mode: Client-side math leaks platform-owned logic into skill packs and fails three-way convergence.
ITDs: aitd-003-close-time-materialization aitd-110-axis-conformance-evidence
Question: How do I audit a derived fact?
API-only rule: Detail/sourceRefs subcollections expose authorized source ids and provenance summaries.
Raw DB plus dictionary rule: Join through source_event_id, source_state_ref, source_result_refs, source_ledger_refs, map refs, or curriculum_scope_refs; do not expect copied source columns in Analytics tables.
Failure mode: A raw query looks for Caliper payload, NWEA raw fields, Results scores, or Curriculum trees duplicated in Analytics.
Question: Which derived rows are reportable by default?
API-only rule: Ordinary list/detail endpoints exclude superseded/tombstoned rows unless includeSuperseded=true and the caller is authorized.
Raw DB plus dictionary rule: Filter superseded_at IS NULL AND source_deleted_at IS NULL for ordinary reports, then apply table-specific quality_status rules.
Failure mode: A raw report double-counts corrections or invalidated source rows.
ITDs: aitd-111-axis-privacy-retention aitd-012-corrections-and-reversals
Question: How do corrections affect totals?
API-only rule: Analytics exposes signed source contributions and report-ready net/display totals.
Raw DB plus dictionary rule: Use signed seconds_delta/negative_xp/net fields exactly as documented; do not clamp, drop, or recompute corrections locally.
Failure mode: A report silently removes negative gaming XP or reversal seconds and stops reconciling.
Question: How are source subjects handled?
API-only rule: Materializers write canonical subject_id or typed null_reason/adapter Problem at write time.
Raw DB plus dictionary rule: Filter/group by subject_id, not source strings such as FastMath, Vocabulary, Science-notqced, ELA, or ISEE variants.
Failure mode: A raw report creates extra subjects or mixes MAP proxy subjects after policy changes.
Question: Is the school-day denominator available, and if so how many active minutes per enrolled school day did this student have?
API-only rule: GET /school-day-minutes returns active_minutes, enrolled_school_day_count, excluded_school_day_count, minutes_per_enrolled_school_day, quality_status, and null_reason at the report grain.
Raw DB plus dictionary rule: Query alpha.analytics_school_day_minutes at the documented grain with quality_status in ('ok','corrected') and null_reason='none' for ordinary reports. source_missing rows are repair states; do not intersect Events with alpha.school_calendar, enrollment windows, processed_facts active dates, or attendance dates in the consumer.
Failure mode: A raw path returns an empty list for a known student, includes weekends/MAP testing days/current-only school assignment, fabricates a denominator from active dates, or renders a source_missing repair row as a completed time-commitment value.
Question: How much XP did a student earn, how much remains, and what percent of the XP goal is complete?
API-only rule: GET /xp-rollups returns xp_total, daily_xp_goal, enrolled_school_day_count, xp_goal, xp_remaining, xp_goal_percent, on_track, signed audit subtotals, source_import provenance, and null_reason.
Raw DB plus dictionary rule: Query alpha.analytics_xp_rollup; use reporting.processed_facts and Results xp_ledger only through authorized source refs, not for report totals, remaining XP, or XP goal percent. Ordinary report rows carry stored denominator-derived goal fields; source_missing means repair/replay is required. Never cap xp_goal_percent at 100 when it is populated.
Failure mode: A client sums TimeBack processed_facts.xp_earned or xp_ledger, then computes goals, remaining XP, or a capped percent locally.
ITDs: aitd-007-xp-rollups aitd-001-report-source-ingestion aitd-004-provenance-no-literals
Question: What percent of reportable questions did the student answer correctly?
API-only rule: GET /accuracy-rollups returns correct_question_count, total_question_count, incorrect_question_count, accuracy_percent, source_import_id, quality_status, and null_reason at the documented student/subject/window grain.
Raw DB plus dictionary rule: Query alpha.analytics_accuracy; use reporting.processed_facts only through source_import/source-ref audit views, never as report math. If total_question_count is zero, read null_reason=no_questions and do not substitute 0% or 100%.
Failure mode: A report computes accuracy by summing raw processed_facts, counting QTI/Events attempts, keeping a private app/source allowlist, or dividing and rounding locally.
ITDs: aitd-001-report-source-ingestion aitd-004-provenance-no-literals aitd-011-policy-and-enum-normalization
Question: Which KCs changed between dates?
API-only rule: GET /mastery-deltas filters by effective_at and state_dimension.
Raw DB plus dictionary rule: Query alpha.analytics_mastery_delta; current state remains Results student_kc_state and mastery math remains Results/Policy.
Failure mode: A report rebuilds mastery/decay/HMG from attempts or treats Analytics as current state of record.
Question: What RIT and Growth X did the student have under a norms set?
API-only rule: GET /map-growth-rollups accepts typed normsSet/growthWindow/term filters and returns report-ready values; the Learning Report "vs 1yr ago" panel requests growthWindow=winter_to_winter.
Raw DB plus dictionary rule: Query alpha.analytics_map_growth_rollup by canonical_term_id, growth_window, and norms_set; for the Learning Report MAP panel read growth_percentile and growth_x from growth_window=winter_to_winter, not fall_to_winter. Do not parse terms, choose retakes, maintain a private norms table, or compute Growth X as observed/typical.
Failure mode: A raw report mixes 2020/2025 norms, selects fall_to_winter for a one-year panel, computes observed/typical, ships a private norms/R90 table, or disagrees with Results/NWEAMap test-of-record.
ITDs: aitd-009-map-growth-rollups aitd-001-report-source-ingestion
Question: What RIT maps to a percentile, and what R90/effective grade maps to a RIT?
API-only rule: GET /norms and /r90/table return versioned readable resources; GET /norms/rit, /norms/percentile, and /r90 return translated values with norms_set, table_version, calculator_version, and source_point_kind where applicable.
Raw DB plus dictionary rule: Read alpha.analytics_norms_achievement by norms_set/table_version/subject_id/role/grade_key/season and apply the documented normal model. Read alpha.analytics_r90_table by table_version='analytics.rit_to_grade.powerpath.v2026-06-15' and table_subject_id, then choose the row whose rit_score equals the requested RIT. Missing subjects/table points return typed missing/validation behavior; missing RIT rows return source_missing rather than a fabricated value.
Failure mode: GOALS, Learning Report, and skill-pack examples disagree because one app cached a private norms table or R90 copy, silently changed versions, chose a nearest row, used an old between-row method, or skipped the current table_version filter.
ITDs: aitd-015-norms-r90-readable-resources aitd-016-scale-translation-apis aitd-017-r90-version-supersession
Question: How many instructional days remain, and what daily effort is needed to finish by the target date?
API-only rule: GET /school-days-remaining returns analytics.school_days_remaining with instructional_days_remaining, instructional_dates, xp_unit.*, effort.*, provenance.*, and links.*. The endpoint uses the half-open [asOf,endDate) window and alpha.policy.analytics.xp_expected_minute.v2026-06-14.
Raw DB plus dictionary rule: Resolve the student's school through People and Orgs effective-dated enrollment, read alpha.school_calendar where calendar_date >= :asOf and calendar_date < :endDate, filter to instructional school days under alpha.policy.school_day.v2026-06-10, exclude MAP-testing days by policy, and apply alpha.policy.analytics.xp_expected_minute.v2026-06-14: 1 XP = 1 expected minute and 60 XP = 1 expected hour. Do not read consumed-day rollups for future dates, count weekdays, use attendance days, parse school_period labels, or hard-code XP_PER_HOUR.
Failure mode: GOALS or a skill pack computes a different target date because it counts weekdays/summer gaps locally, includes MAP days, uses current-only enrollment, treats endDate as inclusive, or carries a private XP_PER_HOUR constant.
ITDs: aitd-018-goals-school-days-remaining aitd-006-school-day-minutes aitd-007-xp-rollups
Question: What progress evidence exists for a course/subject/track?
API-only rule: GET /completion-rollups returns xp_earned, xp_remaining, completion_percent, source_import_id, and null_reason as Analytics evidence.
Raw DB plus dictionary rule: Query alpha.analytics_completion_rollup by completion_scope and scope_id for evidence. Course rows prefer app-reported Caliper percent, then XP remaining; grade_level rows preserve main-course evidence only. Student-facing progress reads come from Results. Do not derive progress from MAP/RIT/R90, walk Curriculum trees, count Results client-side, or use activity flags.
Failure mode: The raw path diverges when a client treats Analytics evidence as the final app-facing answer, treats RIT grade-band percent as actual progress, includes hole-filling courses in grade-level progress, or invents 1-if-active completion.
ITDs: aitd-010-completion-rollups aitd-001-report-source-ingestion aitd-004-provenance-no-literals
Question: Did source-shaped import materialize rows?
API-only rule: POST /source-imports/{adapter} accepts only named adapters; timeback-map accepts full source-shaped hp_map_results rows and ignores unknown extra columns; validation failures return analytics:validation_failed with HTTP 400; adapter rejections return analytics:adapter_rejected with HTTP 422; successful imports report accepted/materialized counts.
Raw DB plus dictionary rule: Migration checks count readable alpha.analytics_* rows plus analytics_source_import.materialized_row_count, not submitted source rows or Problem bodies.
Failure mode: A lying HTTP 200 with zero readable rows, or a timeback-map rejection caused only by unknown extra hp_map_results columns, recreates the migration failure Analytics exists to fix.
ITDs: aitd-001-report-source-ingestion aitd-108-axis-error-envelope aitd-110-axis-conformance-evidence
Reference
POST
/dev/mint?tenantId=demo
Create a short-lived demo JWT. This utility is unauthenticated and only accepts tenantId=demo.
| Name | Type | Required | Description |
|---|---|---|---|
tenantId | TEXT enum | Required | Must be demo. |
| Field | Type | Nullability | Meaning | Source |
|---|---|---|---|---|
token | JWT string | required | Bearer token scoped to the demo tenant. | dictionary |
tenantId | TEXT | required | Tenant claim inside the token. | dictionary |
expiresIn | INTEGER | required | Seconds until the token expires. | dictionary |
curl -sS -X POST "$ANALYTICS_BASE_URL/dev/mint?tenantId=demo"const response = await fetch(`${base}/dev/mint?tenantId=demo`, { method: "POST" });
const { token } = await response.json();{
"token": "demo.analytics.jwt",
"tenantId": "demo",
"expiresIn": 3600
}GET
/alpha/analytics/v1/event-time-facts
Read signed active, inactive, and waste-second contributions written when source Events close. Use this for audit and low-level time tracing.
| Name | Type | Required | Description |
|---|---|---|---|
studentId | TEXT | Optional | Canonical Alpha student id. Omit only for authorized cohort reads. |
subjectId | subject_id enum | Optional | Canonical subject after server-side subject normalization. |
startDate | DATE | Optional | Inclusive start date in the school/reporting timezone. |
endDate | DATE | Optional | Exclusive end date. Must be later than startDate. |
modifiedSince | TIMESTAMPTZ | Optional | UTC ISO-8601 polling checkpoint over modified_at. |
limit | INTEGER | Optional | Page size. Default 100; maximum 1000. |
cursor | TEXT | Optional | Opaque next-page cursor returned by the previous page. |
factKind | fact_kind enum | Optional | active_seconds, inactive_seconds, or waste_seconds. |
sourceEventId | TEXT | Optional | Events Alpha event id that produced the fact. |
| Field | Type | Nullability | Meaning | Source |
|---|---|---|---|---|
id | UUID | required | Analytics-owned stable row id for this derived fact. Generated by the platform; globally unique within alpha.analytics_* objects. | dictionary |
student_id | TEXT | required | Canonical Alpha student id the source Event or Result resolved to at materialization time. Must resolve through People and Orgs as a real student for the source timestamp/effective date. | dictionary |
source_event_id | TEXT | required | Events Alpha event id this contribution derives from. Must reference one closed Events row in the same tenant. | dictionary |
fact_kind | TEXT enum | required | Which time bucket this signed contribution belongs to. Allowed values: fact_kind enum. Set by the versioned time-classification policy named in policy_ref, for example alpha.policy.analytics.time_classification.v2026-06-10. | dictionary |
seconds_delta | NUMERIC(14,3) | required | Signed seconds contributed by this source event to the fact_kind bucket. May be negative for correction/reversal rows; ordinary display measures use rollup fields, not client-side clamping. | dictionary |
subject_id | TEXT | nullable where the row is all-subject or the source cannot validly resolve a subject | Canonical Alpha subject used for reporting and grouping. Closed Alpha subject enum after write-time alias folds; unknown source subject becomes an adapter finding or null_reason, not a new string. | dictionary |
application_ref | TEXT | nullable | Application/activity-source reference resolved from the source event when available. Reference only; application identity/lifecycle belongs to Applications. | dictionary |
policy_ref | TEXT | required | Named policy/config version used to compute the measure or rollup. Must point at alpha.policy.analytics.* or an inherited Curriculum/Results policy active for the source effective date. | dictionary |
quality_status | TEXT enum | required | Current materialization quality state for this fact. Allowed values: quality_status enum. Ordinary report reads keep ok, corrected, and signed reversed rows according to the table rule; audit reads may include source_missing/source_unlinked/policy_pending/adapter_rejected. | dictionary |
modified_at | TIMESTAMPTZ | required | Last time the Analytics row changed for polling and modifiedSince queries. UTC timestamp; list endpoints support modifiedSince against this field. | dictionary |
curl -sS "$ANALYTICS_BASE_URL/alpha/analytics/v1/event-time-facts?studentId=student_01HT7G3YZV7QB5N4YKQ1K0Z9A9&factKind=active_seconds&startDate=2026-05-01&endDate=2026-06-01" \
-H "Authorization: Bearer $ANALYTICS_TOKEN"const response = await fetch(`${base}/alpha/analytics/v1/event-time-facts`, { headers: { Authorization: `Bearer ${token}` } });
if (!response.ok) throw await response.json();
const body = await response.json();{
"object": "list",
"url": "/alpha/analytics/v1/event-time-facts",
"data": [
{
"id": "8e9c0ef2-bc75-4f53-8124-df77df49f25f",
"student_id": "student_01HT7G3YZV7QB5N4YKQ1K0Z9A9",
"source_event_id": "evt_alpha_000891",
"fact_kind": "active_seconds",
"seconds_delta": 420,
"subject_id": "math",
"application_ref": "app_math_academy",
"policy_ref": "alpha.policy.analytics.time_classification.v2026-06-10",
"quality_status": "ok",
"modified_at": "2026-05-14T18:32:22Z"
}
],
"hasMore": false,
"nextCursor": null,
"links": {
"self": "/alpha/analytics/v1/event-time-facts"
}
}GET
/alpha/analytics/v1/time-windows
Read active, inactive, waste, and display minutes by student, subject, and reporting window.
| Name | Type | Required | Description |
|---|---|---|---|
studentId | TEXT | Optional | Canonical Alpha student id. Omit only for authorized cohort reads. |
subjectId | subject_id enum | Optional | Canonical subject after server-side subject normalization. |
startDate | DATE | Optional | Inclusive start date in the school/reporting timezone. |
endDate | DATE | Optional | Exclusive end date. Must be later than startDate. |
modifiedSince | TIMESTAMPTZ | Optional | UTC ISO-8601 polling checkpoint over modified_at. |
limit | INTEGER | Optional | Page size. Default 100; maximum 1000. |
cursor | TEXT | Optional | Opaque next-page cursor returned by the previous page. |
windowKind | window_kind enum | Optional | day, week, term, school_year, or custom. |
| Field | Type | Nullability | Meaning | Source |
|---|---|---|---|---|
id | UUID | required | Analytics-owned stable row id for this derived fact. Generated by the platform; globally unique within alpha.analytics_* objects. | dictionary |
student_id | TEXT | required | Canonical Alpha student id the source Event or Result resolved to at materialization time. Must resolve through People and Orgs as a real student for the source timestamp/effective date. | dictionary |
subject_id | TEXT | nullable where the row is all-subject or the source cannot validly resolve a subject | Canonical Alpha subject used for reporting and grouping. Closed Alpha subject enum after write-time alias folds; unknown source subject becomes an adapter finding or null_reason, not a new string. | dictionary |
window_kind | TEXT enum | required | Named window family for this rollup. Allowed values: window_kind enum; custom requires explicit policy/window metadata. | dictionary |
window_start | DATE | required | Inclusive start date of the reporting window in the school timezone. Must be before window_end; ISO date. | dictionary |
window_end | DATE | required | Exclusive end date of the reporting window in the school timezone. Must be after window_start; ISO date. | dictionary |
active_seconds_total | NUMERIC(14,3) | required | Net active seconds from current event_time_fact rows in this window. Can include signed corrections; display fields apply policy presentation. | dictionary |
inactive_seconds_total | NUMERIC(14,3) | required | Net inactive seconds from current event_time_fact rows in this window. Can include signed corrections. | dictionary |
waste_seconds_total | NUMERIC(14,3) | required | Net waste/gaming seconds from current event_time_fact rows in this window. Can be positive or negative after corrections. | dictionary |
display_active_minutes | NUMERIC(12,3) | required | Policy-defined active minutes shown in reports for this time window. Computed by Analytics from active_seconds_total under policy_ref; consumers read it directly. | dictionary |
quality_status | TEXT enum | required | Current materialization quality state for this fact. Allowed values: quality_status enum. Ordinary report reads keep ok, corrected, and signed reversed rows according to the table rule; audit reads may include source_missing/source_unlinked/policy_pending/adapter_rejected. | dictionary |
modified_at | TIMESTAMPTZ | required | Last time the Analytics row changed for polling and modifiedSince queries. UTC timestamp; list endpoints support modifiedSince against this field. | dictionary |
curl -sS "$ANALYTICS_BASE_URL/alpha/analytics/v1/time-windows?studentId=student_01HT7G3YZV7QB5N4YKQ1K0Z9A9&subjectId=math&windowKind=day&startDate=2026-05-01&endDate=2026-06-01" \
-H "Authorization: Bearer $ANALYTICS_TOKEN"const response = await fetch(`${base}/alpha/analytics/v1/time-windows`, { headers: { Authorization: `Bearer ${token}` } });
if (!response.ok) throw await response.json();
const body = await response.json();{
"object": "list",
"url": "/alpha/analytics/v1/time-windows",
"data": [
{
"id": "1b0d98de-8f58-4ec3-9f2b-5cfbfa3d0001",
"student_id": "student_01HT7G3YZV7QB5N4YKQ1K0Z9A9",
"subject_id": "math",
"window_kind": "day",
"window_start": "2026-05-14",
"window_end": "2026-05-15",
"active_seconds_total": 3240,
"inactive_seconds_total": 120,
"waste_seconds_total": 0,
"display_active_minutes": 54,
"quality_status": "ok",
"modified_at": "2026-05-14T23:59:59Z"
}
],
"hasMore": false,
"nextCursor": null,
"links": {
"self": "/alpha/analytics/v1/time-windows"
}
}GET
/alpha/analytics/v1/school-day-minutes
Read active minutes, enrolled-school-day denominator, MAP-day exclusions, and null_reason when the calendar prerequisite is not yet materialized.
| Name | Type | Required | Description |
|---|---|---|---|
studentId | TEXT | Optional | Canonical Alpha student id. Omit only for authorized cohort reads. |
subjectId | subject_id enum | Optional | Canonical subject after server-side subject normalization. |
startDate | DATE | Optional | Inclusive start date in the school/reporting timezone. |
endDate | DATE | Optional | Exclusive end date. Must be later than startDate. |
modifiedSince | TIMESTAMPTZ | Optional | UTC ISO-8601 polling checkpoint over modified_at. |
limit | INTEGER | Optional | Page size. Default 100; maximum 1000. |
cursor | TEXT | Optional | Opaque next-page cursor returned by the previous page. |
schoolId | TEXT | Optional | People and Orgs school id used for the calendar denominator. |
includeUnavailable | BOOLEAN | Optional | When true, include current source_missing or policy_pending rows for UI explanation. |
| Field | Type | Nullability | Meaning | Source |
|---|---|---|---|---|
id | UUID | required | Analytics-owned stable row id for this derived fact. Generated by the platform; globally unique within alpha.analytics_* objects. | dictionary |
student_id | TEXT | required | Canonical Alpha student id the source Event or Result resolved to at materialization time. Must resolve through People and Orgs as a real student for the source timestamp/effective date. | dictionary |
school_id | TEXT | required | People and Orgs school whose calendar/enrollment intersection defines the denominator. Must resolve as the student school for the effective range; no current-only shortcut. | dictionary |
subject_id | TEXT | nullable; null means all reportable subjects | Canonical Alpha subject used for reporting and grouping. Closed Alpha subject enum after write-time alias folds; unknown source subject becomes an adapter finding or null_reason, not a new string. | dictionary |
window_start | DATE | required | Inclusive start date for the denominator/numerator window. ISO date; half-open range with window_end. | dictionary |
window_end | DATE | required | Exclusive end date for the denominator/numerator window. ISO date; must be after window_start. | dictionary |
active_minutes | NUMERIC(12,3) | required | Policy-defined active minutes for the same window and subject grain. Normalized by the timeback-xp-time-accuracy adapter from reporting.processed_facts.active_seconds, then stored as minutes under policy_ref. | dictionary |
enrolled_school_day_count | INTEGER | required when null_reason=none; nullable only for source_missing repair rows | Denominator: school days intersecting the student effective-dated enrollment and subject assignment when subject_id is present. Nonnegative; excludes weekends, holidays, teacher-workshop days, MAP-testing days, and non-time-locatable enrollments. Null only with a typed repair reason such as source_missing. | dictionary |
excluded_school_day_count | INTEGER | required when null_reason=none; nullable only for source_missing repair rows | Calendar dates inside the requested window that the school-day policy excluded from the denominator. Nonnegative; includes weekend, holiday_break, teacher_workshop, nwea_map_testing, and governed other exclusions. Null only with a typed repair reason such as source_missing. | dictionary |
minutes_per_enrolled_school_day | NUMERIC(12,3) | nullable when denominator is zero or policy/source is missing | Report-ready average active minutes per enrolled school day when the school-day denominator source is available. Formula: round(active_minutes / enrolled_school_day_count, 3) when enrolled_school_day_count > 0 and null_reason=none. Null requires null_reason other than none; consumers never recompute the denominator or substitute active days. | dictionary |
school_day_policy_ref | TEXT | required | Named policy/config version used to compute the measure or rollup. Must point at alpha.policy.analytics.* or an inherited Curriculum/Results policy active for the source effective date. | dictionary |
null_reason | TEXT enum | required | Why minutes_per_enrolled_school_day and denominator counts are null or not reportable. Allowed values: null_reason enum. none means the metric is populated; source_missing means the required calendar source does not exist or is unavailable and the row is not reportable. | dictionary |
quality_status | TEXT enum | required | Current materialization quality state for this school-day denominator row. Allowed values: quality_status enum. Ordinary Learning Report rows are ok or corrected; source_missing is a readable repair state when the calendar source is unavailable. | dictionary |
modified_at | TIMESTAMPTZ | required | Last time the Analytics row changed for polling and modifiedSince queries. UTC timestamp; list endpoints support modifiedSince against this field. | dictionary |
curl -sS "$ANALYTICS_BASE_URL/alpha/analytics/v1/school-day-minutes?studentId=student_01HT7G3YZV7QB5N4YKQ1K0Z9A9&subjectId=math&startDate=2026-05-01&endDate=2026-06-01&includeUnavailable=true" \
-H "Authorization: Bearer $ANALYTICS_TOKEN"const response = await fetch(`${base}/alpha/analytics/v1/school-day-minutes`, { headers: { Authorization: `Bearer ${token}` } });
if (!response.ok) throw await response.json();
const body = await response.json();{
"object": "list",
"url": "/alpha/analytics/v1/school-day-minutes",
"data": [
{
"id": "2d4b32cd-c4d8-4e45-8a3a-9de8ce3b0002",
"student_id": "student_01HT7G3YZV7QB5N4YKQ1K0Z9A9",
"school_id": "school_alpha_austin",
"subject_id": "math",
"window_start": "2026-05-01",
"window_end": "2026-06-01",
"active_minutes": 1080,
"enrolled_school_day_count": 20,
"excluded_school_day_count": 2,
"minutes_per_enrolled_school_day": 54,
"school_day_policy_ref": "alpha.policy.school_day.v2026-06-10",
"null_reason": "none",
"quality_status": "ok",
"modified_at": "2026-06-01T01:00:00Z"
}
],
"hasMore": false,
"nextCursor": null,
"links": {
"self": "/alpha/analytics/v1/school-day-minutes"
}
}GET
/alpha/analytics/v1/xp-rollups
Read report-ready XP totals, goals, remaining XP, and signed correction subtotals while Results remains the immutable XP ledger.
| Name | Type | Required | Description |
|---|---|---|---|
studentId | TEXT | Optional | Canonical Alpha student id. Omit only for authorized cohort reads. |
subjectId | subject_id enum | Optional | Canonical subject after server-side subject normalization. |
startDate | DATE | Optional | Inclusive start date in the school/reporting timezone. |
endDate | DATE | Optional | Exclusive end date. Must be later than startDate. |
modifiedSince | TIMESTAMPTZ | Optional | UTC ISO-8601 polling checkpoint over modified_at. |
limit | INTEGER | Optional | Page size. Default 100; maximum 1000. |
cursor | TEXT | Optional | Opaque next-page cursor returned by the previous page. |
windowKind | window_kind enum | Optional | day, week, term, school_year, or custom. |
| Field | Type | Nullability | Meaning | Source |
|---|---|---|---|---|
id | UUID | required | Analytics-owned stable row id for this derived fact. Generated by the platform; globally unique within alpha.analytics_* objects. | dictionary |
student_id | TEXT | required | Canonical Alpha student id the source Event or Result resolved to at materialization time. Must resolve through People and Orgs as a real student for the source timestamp/effective date. | dictionary |
subject_id | TEXT | nullable where the row is all-subject or the source cannot validly resolve a subject | Canonical Alpha subject used for reporting and grouping. Closed Alpha subject enum after write-time alias folds; unknown source subject becomes an adapter finding or null_reason, not a new string. | dictionary |
window_kind | TEXT enum | required | Named window family for the XP rollup. Allowed values: window_kind enum. | dictionary |
window_start | DATE | required | Inclusive start date for included XP ledger effective dates. ISO date; half-open with window_end. | dictionary |
window_end | DATE | required | Exclusive end date for included XP ledger effective dates. ISO date; must be after window_start. | dictionary |
positive_xp | NUMERIC(14,3) | required | Positive XP contribution subtotal retained for audit/explanation. Nonnegative; normalized by the adapter/materializer, with Results xp_ledger refs when available. | dictionary |
negative_xp | NUMERIC(14,3) | required | Sum of negative XP penalties/reversals in this rollup. Zero or negative; gaming/cheating signals and reversals stay signed. | dictionary |
xp_total | NUMERIC(14,3) | required | Policy-defined report XP total after the report-source adapter applies subject folds, exclusions, corrections, and signed contributions. Non-null values require source_import_id provenance; should equal the report value for this student/subject/window. | dictionary |
net_xp | NUMERIC(14,3) | required | Signed audit total after positive and negative XP contributions; equal to xp_total for ordinary report rows under the current policy. positive_xp + negative_xp under policy_ref; retained for correction/reversal reconciliation. | dictionary |
xp_goal | NUMERIC(14,3) | required when null_reason=none; nullable only when enrolled_school_day_count or XP goal policy is missing | Window XP target for this student, subject, and window, used by the Learning Report XP Remaining and XP Goal Percent panels. Nonnegative when populated; equals daily_xp_goal multiplied by enrolled_school_day_count when both are present. Null requires a typed repair reason such as source_missing or policy_pending. | dictionary |
daily_xp_goal | NUMERIC(14,3) | nullable when daily XP policy is missing | Daily XP target used in the auditor-pinned XP goal percent denominator. Nonnegative; read from alpha.policy.analytics.xp_goal_percent.v1 / Curriculum Policy, never from a consumer constant. | dictionary |
enrolled_school_day_count | INTEGER | required when null_reason=none; nullable only when school-day denominator source is missing | Number of days in the XP percent denominator: days the student was enrolled and school was in session. Nonnegative integer when populated. Enrollment begin/end bound the count; the student's school calendar governs it; MAP testing days are excluded; per-subject rows count only days with a subject assignment. Null requires a typed repair reason such as source_missing. | dictionary |
xp_remaining | NUMERIC(14,3) | required when null_reason=none; nullable when xp_goal is null/source_missing | Report-ready remaining XP under policy_ref. max(xp_goal - xp_total, 0) under policy_ref when xp_goal is present; stored by Analytics so reports do not subtract locally. Null requires a typed repair reason. | dictionary |
xp_goal_percent | NUMERIC(9,3) | nullable when daily_xp_goal or enrolled_school_day_count is null or zero | Uncapped percent of the XP goal reached in this window when the school-day denominator is available. Formula under alpha.policy.analytics.xp_goal_percent.v1 when populated: xp_total / (daily_xp_goal x enrolled_school_day_count) x 100. Values above 100 are valid and must remain visible. Null requires a typed repair reason. | dictionary |
xp_completion_percent | NUMERIC(9,3) | deprecated compatibility alias; nullability matches xp_goal_percent | Deprecated compatibility alias for xp_goal_percent. Must equal xp_goal_percent exactly and remains uncapped. It has no independent capped-completion meaning. Nullability matches xp_goal_percent. | dictionary |
on_track | BOOLEAN | nullable when xp_goal_percent is null | Whether the student is on track against the XP goal policy for this window. Computed under policy_ref; null means the goal policy or denominator is missing. | dictionary |
award_count | INTEGER | required | Number of positive or neutral XP ledger rows contributing to this rollup. Nonnegative; excludes superseded rows unless audit query requests them. | dictionary |
reversal_count | INTEGER | required | Number of reversal/correction XP ledger rows included. Nonnegative. | dictionary |
source_import_id | TEXT | required for report-tile rows; nullable for purely derived event-axis rows | Analytics source-import receipt that proves which named report-source adapter produced this report-grade fact. Must reference alpha.analytics_source_import for non-null Learning Report tile values; no literal or fixture value may be reportable without this provenance. | dictionary |
quality_status | TEXT enum | required | Current materialization quality state for this fact. Allowed values: quality_status enum. Ordinary report reads keep ok, corrected, and signed reversed rows according to the table rule; audit reads may include source_missing/source_unlinked/policy_pending/adapter_rejected. | dictionary |
null_reason | TEXT enum | required | Why XP goal fields are null or unavailable while xp_total itself may still be reportable. Allowed values: null_reason enum. none means xp_goal, xp_remaining, xp_goal_percent, and on_track are populated; source_missing means the shared school-day denominator source is absent and the goal fields are not reportable. | dictionary |
modified_at | TIMESTAMPTZ | required | Last time the Analytics row changed for polling and modifiedSince queries. UTC timestamp; list endpoints support modifiedSince against this field. | dictionary |
curl -sS "$ANALYTICS_BASE_URL/alpha/analytics/v1/xp-rollups?studentId=student_01HT7G3YZV7QB5N4YKQ1K0Z9A9&subjectId=math&windowKind=term&startDate=2026-01-01&endDate=2026-06-01" \
-H "Authorization: Bearer $ANALYTICS_TOKEN"const response = await fetch(`${base}/alpha/analytics/v1/xp-rollups`, { headers: { Authorization: `Bearer ${token}` } });
if (!response.ok) throw await response.json();
const body = await response.json();{
"object": "list",
"url": "/alpha/analytics/v1/xp-rollups",
"data": [
{
"id": "3f2b79e1-6182-4e21-a0b6-7d6cf7530003",
"student_id": "student_01HT7G3YZV7QB5N4YKQ1K0Z9A9",
"subject_id": "math",
"window_kind": "term",
"window_start": "2026-01-01",
"window_end": "2026-06-01",
"positive_xp": 11850,
"negative_xp": -50,
"xp_total": 11800,
"net_xp": 11800,
"xp_goal": 9000,
"daily_xp_goal": 100,
"enrolled_school_day_count": 90,
"xp_remaining": 0,
"xp_goal_percent": 131.111,
"xp_completion_percent": 131.111,
"on_track": true,
"award_count": 24,
"reversal_count": 1,
"source_import_id": "imp_01HT8XPTIME_2026_SPRING",
"quality_status": "ok",
"null_reason": "none",
"modified_at": "2026-06-01T01:02:00Z"
}
],
"hasMore": false,
"nextCursor": null,
"links": {
"self": "/alpha/analytics/v1/xp-rollups"
}
}GET
/alpha/analytics/v1/accuracy-rollups
Read report-ready correct questions, total questions, incorrect questions, and accuracy percent without client-side processed_facts math.
| Name | Type | Required | Description |
|---|---|---|---|
studentId | TEXT | Optional | Canonical Alpha student id. Omit only for authorized cohort reads. |
subjectId | subject_id enum | Optional | Canonical subject after server-side subject normalization. |
startDate | DATE | Optional | Inclusive start date in the school/reporting timezone. |
endDate | DATE | Optional | Exclusive end date. Must be later than startDate. |
modifiedSince | TIMESTAMPTZ | Optional | UTC ISO-8601 polling checkpoint over modified_at. |
limit | INTEGER | Optional | Page size. Default 100; maximum 1000. |
cursor | TEXT | Optional | Opaque next-page cursor returned by the previous page. |
windowKind | window_kind enum | Optional | day, week, term, school_year, or custom. |
| Field | Type | Nullability | Meaning | Source |
|---|---|---|---|---|
id | UUID | required | Analytics-owned stable row id for this derived fact. Generated by the platform; globally unique within alpha.analytics_* objects. | dictionary |
student_id | TEXT | required | Canonical Alpha student id the source Event or Result resolved to at materialization time. Must resolve through People and Orgs as a real student for the source timestamp/effective date. | dictionary |
subject_id | TEXT | nullable where the row is all-subject or the source cannot validly resolve a subject | Canonical Alpha subject used for reporting and grouping. Closed Alpha subject enum after write-time alias folds; unknown source subject becomes an adapter finding or null_reason, not a new string. | dictionary |
window_kind | TEXT enum | required | Named window family for the Accuracy rollup. Allowed values: window_kind enum. | dictionary |
window_start | DATE | required | Inclusive start date for source question rows included in this rollup. ISO date; half-open with window_end. | dictionary |
window_end | DATE | required | Exclusive end date for source question rows included in this rollup. ISO date; must be after window_start. | dictionary |
correct_question_count | INTEGER | required | Reportable correct-question numerator after the adapter applies subject, app/source, score_type, correction, and real-student rules. Nonnegative integer; cannot exceed total_question_count when total_question_count is present. Normalized from source-shaped reporting.processed_facts.correct_questions, not read by reports from the source table. | dictionary |
total_question_count | INTEGER | required | Reportable question-attempt denominator after the adapter applies the same policy filters as correct_question_count. Nonnegative integer. Zero is allowed only with null_reason=no_questions and null accuracy_percent. | dictionary |
incorrect_question_count | INTEGER | required | Reportable incorrect-question count retained for explanations. Nonnegative integer; equals total_question_count - correct_question_count under the policy version. | dictionary |
accuracy_percent | NUMERIC(9,3) | nullable when total_question_count is zero or source/policy is missing | Report-ready percent of reportable questions answered correctly. 0 through 100 when populated; null requires a typed null_reason. Formula and rounding are owned by Analytics under policy_ref. | dictionary |
source_import_id | TEXT | required for report-tile rows; nullable for purely derived event-axis rows | Analytics source-import receipt that proves which named report-source adapter produced this report-grade fact. Must reference alpha.analytics_source_import for non-null Learning Report tile values; no literal or fixture value may be reportable without this provenance. | dictionary |
source_fact_refs | JSONB | required | Compact ids/hashes/cursor for source-shaped processed_facts rows accepted by the adapter. Stores refs/hashes only; never copies raw processed_facts rows or student identifiers. | dictionary |
quality_status | TEXT enum | required | Current materialization quality state for this fact. Allowed values: quality_status enum. Ordinary report reads keep ok, corrected, and signed reversed rows according to the table rule; audit reads may include source_missing/source_unlinked/policy_pending/adapter_rejected. | dictionary |
null_reason | TEXT enum | required | Why accuracy_percent is null or not reportable. Allowed values: null_reason enum. no_questions means the source window had zero reportable question attempts; none means the metric is populated. | dictionary |
modified_at | TIMESTAMPTZ | required | Last time the Analytics row changed for polling and modifiedSince queries. UTC timestamp; list endpoints support modifiedSince against this field. | dictionary |
curl -sS "$ANALYTICS_BASE_URL/alpha/analytics/v1/accuracy-rollups?studentId=student_01HT7G3YZV7QB5N4YKQ1K0Z9A9&subjectId=math&windowKind=term&startDate=2026-01-01&endDate=2026-06-01" \
-H "Authorization: Bearer $ANALYTICS_TOKEN"const response = await fetch(`${base}/alpha/analytics/v1/accuracy-rollups`, { headers: { Authorization: `Bearer ${token}` } });
if (!response.ok) throw await response.json();
const body = await response.json();{
"object": "list",
"url": "/alpha/analytics/v1/accuracy-rollups",
"data": [
{
"id": "9c3f3e4f-1fd8-4c28-8a72-cbbf2e6d0006",
"student_id": "student_01HT7G3YZV7QB5N4YKQ1K0Z9A9",
"subject_id": "math",
"window_kind": "term",
"window_start": "2026-01-01",
"window_end": "2026-06-01",
"correct_question_count": 480,
"total_question_count": 600,
"incorrect_question_count": 120,
"accuracy_percent": 80,
"source_import_id": "imp_01HT8XPTIME_2026_SPRING",
"source_fact_refs": [
"processed_facts_hash_01HT7Q"
],
"quality_status": "ok",
"null_reason": "none",
"modified_at": "2026-06-01T01:02:30Z"
}
],
"hasMore": false,
"nextCursor": null,
"links": {
"self": "/alpha/analytics/v1/accuracy-rollups"
}
}GET
/alpha/analytics/v1/mastery-deltas
Read dated changes in Results-owned KC mastery state. The current state remains in Results; Analytics reports what changed in the window.
| Name | Type | Required | Description |
|---|---|---|---|
studentId | TEXT | Optional | Canonical Alpha student id. |
kcId | TEXT | Optional | Knowledge Component id. |
stateDimension | state_dimension enum | Optional | durable mastery, working grade, highest mastered grade, or another governed dimension. |
transitionKind | transition_kind enum | Optional | How the state changed. |
startDate | DATE | Optional | Inclusive boundary for effective_at. |
endDate | DATE | Optional | Exclusive boundary for effective_at. |
modifiedSince | TIMESTAMPTZ | Optional | Poll for changed rows. |
limit | INTEGER | Optional | Page size. Default 100; maximum 1000. |
cursor | TEXT | Optional | Opaque next-page cursor. |
| Field | Type | Nullability | Meaning | Source |
|---|---|---|---|---|
id | UUID | required | Analytics-owned stable row id for this derived fact. Generated by the platform; globally unique within alpha.analytics_* objects. | dictionary |
student_id | TEXT | required | Canonical Alpha student id the source Event or Result resolved to at materialization time. Must resolve through People and Orgs as a real student for the source timestamp/effective date. | dictionary |
kc_id | TEXT | nullable when the row is a grade-level mastered fact without a single KC | Knowledge Component whose student state changed. Must reference a Curriculum KC; never a standard or lesson id. | dictionary |
grade_subject | TEXT enum | nullable except grade-level mastered rows | Subject for a Grade Levels Mastered row shown in the Learning Report. Closed Alpha subject enum after write-time normalization; required when grade_level/completed_on are populated. | dictionary |
grade_level | INTEGER | nullable except grade-level mastered rows | Grade level the student has mastered in the subject. Positive integer; set by the grade-mastery adapter from passed gate/assessment evidence. | dictionary |
state_dimension | TEXT enum | required | Which Results mastery-state dimension changed. Allowed values: state_dimension enum. | dictionary |
effective_at | TIMESTAMPTZ | required | When the state transition is effective for as-of reporting. UTC timestamp; comes from Results state transition, not Analytics computed_at. | dictionary |
previous_value | JSONB | nullable | Typed previous value for the changed state dimension. JSON shape must match state_dimension; null allowed for first known state. | dictionary |
new_value | JSONB | required | Typed new value for the changed state dimension. JSON shape must match state_dimension. | dictionary |
delta_value | NUMERIC(12,6) | nullable | Numeric difference where the state dimension has a numeric value. Null for non-numeric dimensions such as next_due_at or fluency_state. | dictionary |
transition_kind | TEXT enum | required | Human-readable category of the state transition. Allowed values: acquired, improved, decayed, review_due, fluency_changed, corrected, blocked. Set by Results/Analytics materializer policy; reports group by this value instead of classifying attempts. | dictionary |
source_result_refs | JSONB | required | Result/evidence ids that caused or explain the state transition or grade-level mastery fact. Stores ids/hashes only; no raw scored payload copies. | dictionary |
quality_status | TEXT enum | required | Current materialization quality state for this fact. Allowed values: quality_status enum. Ordinary report reads keep ok, corrected, and signed reversed rows according to the table rule; audit reads may include source_missing/source_unlinked/policy_pending/adapter_rejected. | dictionary |
modified_at | TIMESTAMPTZ | required | Last time the Analytics row changed for polling and modifiedSince queries. UTC timestamp; list endpoints support modifiedSince against this field. | dictionary |
curl -sS "$ANALYTICS_BASE_URL/alpha/analytics/v1/mastery-deltas?studentId=student_01HT7G3YZV7QB5N4YKQ1K0Z9A9&stateDimension=durable_mastery&startDate=2026-05-01&endDate=2026-06-01" \
-H "Authorization: Bearer $ANALYTICS_TOKEN"const response = await fetch(`${base}/alpha/analytics/v1/mastery-deltas`, { headers: { Authorization: `Bearer ${token}` } });
if (!response.ok) throw await response.json();
const body = await response.json();{
"object": "list",
"url": "/alpha/analytics/v1/mastery-deltas",
"data": [
{
"id": "4e9268b7-e76a-46d9-9b6e-899aa2df0004",
"student_id": "student_01HT7G3YZV7QB5N4YKQ1K0Z9A9",
"kc_id": "kc_math_fraction_addition_unlike_denominators",
"grade_subject": "math",
"grade_level": 5,
"state_dimension": "durable_mastery",
"effective_at": "2026-05-14T18:45:00Z",
"previous_value": {
"value": 0.82
},
"new_value": {
"value": 0.91
},
"delta_value": 0.09,
"transition_kind": "acquired",
"source_result_refs": [
"result_01HT7K8BR3",
"result_kc_evidence_01HT7K8BR3_KC"
],
"quality_status": "ok",
"modified_at": "2026-05-14T18:45:04Z"
}
],
"hasMore": false,
"nextCursor": null,
"links": {
"self": "/alpha/analytics/v1/mastery-deltas"
}
}GET
/alpha/analytics/v1/map-growth-rollups
Read report-ready RIT, achievement percentile, growth percentile, Growth X, target, on-track state, sitting count, and retake count.
| Name | Type | Required | Description |
|---|---|---|---|
studentId | TEXT | Optional | Canonical Alpha student id. |
subjectId | subject_id enum | Optional | Canonical Alpha subject id. |
termId | TEXT | Optional | Public API alias for canonical_term_id. |
growthWindow | growth_window enum | Optional | Use winter_to_winter for the Learning Report vs one-year panel. |
normsSet | norms_set enum | Optional | 2020 or 2025. This selects stored rollup rows; clients do not carry norm tables. |
modifiedSince | TIMESTAMPTZ | Optional | Poll for changed rows. |
limit | INTEGER | Optional | Page size. Default 100; maximum 1000. |
cursor | TEXT | Optional | Opaque next-page cursor. |
| Field | Type | Nullability | Meaning | Source |
|---|---|---|---|---|
id | UUID | required | Analytics-owned stable row id for this derived fact. Generated by the platform; globally unique within alpha.analytics_* objects. | dictionary |
student_id | TEXT | required | Canonical Alpha student id the source Event or Result resolved to at materialization time. Must resolve through People and Orgs as a real student for the source timestamp/effective date. | dictionary |
subject_id | TEXT | required for MAP rollups | Canonical Alpha subject used for reporting and grouping. Closed Alpha subject enum after write-time alias folds; unknown source subject becomes an adapter finding or null_reason, not a new string. | dictionary |
canonical_term_id | TEXT | required | Alpha canonical term id for the MAP observation/window. Set by Results/NWEAMap term normalization; not parsed by Analytics clients. | dictionary |
growth_window | TEXT enum | required | MAP growth interval represented by this row. Allowed values: growth_window enum. | dictionary |
norms_set | TEXT enum | required | NWEA norms family used for projected growth and normed outputs. Allowed values: norms_set enum; the same report can be regenerated by changing this filter. | dictionary |
rit_score | NUMERIC(6,2) | required | Report-ready RIT value from Results MAP test-of-record for this subject/term. Positive numeric; no local test-of-record choice in Analytics clients. | dictionary |
achievement_percentile | NUMERIC(6,2) | nullable when the MAP source row has no achievement percentile | Achievement percentile for the test-of-record sitting. 0 to 100 when present; for hp_map_results this is normalized from testpercentile. | dictionary |
growth_percentile | NUMERIC(6,2) | nullable when the selected growth_window has no conditional growth percentile | Conditional growth percentile for the selected MAP window; the Learning Report "vs 1yr ago" panel reads this from the winter_to_winter row. 0 to 100 when present; null requires null_reason for report windows that should have growth. | dictionary |
observed_growth | NUMERIC(7,3) | nullable when no paired window exists | Actual RIT growth for the growth_window. Null for term-only observations; otherwise computed by Results MAP views. | dictionary |
projected_growth | NUMERIC(7,3) | nullable when no projected growth exists | NWEA projected-growth value for the selected window. Must be greater than 0 when growth_x is present; comes from Results/NWEAMap normalized projections and never from a client norms table. | dictionary |
growth_x | NUMERIC(8,4) | nullable when observed or projected growth is unavailable | Observed growth divided by projected_growth, using the named norms_set and growth_window. Null requires null_reason; target comparisons use growth_x_target. | dictionary |
growth_x_target | NUMERIC(8,4) | required | Alpha target Growth X for intervention/on-track decisions. Normally 2 under current Alpha policy, but read from policy_ref. | dictionary |
on_track | BOOLEAN | nullable when growth_x or target is null | Whether the student is meeting the Growth X target for this row. Computed under policy_ref; null requires null_reason. | dictionary |
sitting_count | INTEGER | required | Number of MAP sittings Results observed for this subject/term before test-of-record selection. Nonnegative; includes source-visible sittings according to Results policy. | dictionary |
retake_count | INTEGER | required | Number of non-test-of-record sittings represented by the sitting_count. Nonnegative; computed by Results/NWEAMap policy. | dictionary |
source_import_id | TEXT | required for report-tile rows; nullable for purely derived event-axis rows | Analytics source-import receipt that proves which named report-source adapter produced this report-grade fact. Must reference alpha.analytics_source_import for non-null Learning Report tile values; no literal or fixture value may be reportable without this provenance. | dictionary |
quality_status | TEXT enum | required | Current materialization quality state for this fact. Allowed values: quality_status enum. Ordinary report reads keep ok, corrected, and signed reversed rows according to the table rule; audit reads may include source_missing/source_unlinked/policy_pending/adapter_rejected. | dictionary |
modified_at | TIMESTAMPTZ | required | Last time the Analytics row changed for polling and modifiedSince queries. UTC timestamp; list endpoints support modifiedSince against this field. | dictionary |
curl -sS "$ANALYTICS_BASE_URL/alpha/analytics/v1/map-growth-rollups?studentId=student_01HT7G3YZV7QB5N4YKQ1K0Z9A9&subjectId=math&termId=term_2026_winter&growthWindow=winter_to_winter&normsSet=2025" \
-H "Authorization: Bearer $ANALYTICS_TOKEN"const response = await fetch(`${base}/alpha/analytics/v1/map-growth-rollups`, { headers: { Authorization: `Bearer ${token}` } });
if (!response.ok) throw await response.json();
const body = await response.json();{
"object": "list",
"url": "/alpha/analytics/v1/map-growth-rollups",
"data": [
{
"id": "5a41fb2a-5d08-45fd-a62b-58a518060005",
"student_id": "student_01HT7G3YZV7QB5N4YKQ1K0Z9A9",
"subject_id": "math",
"canonical_term_id": "term_2026_winter",
"growth_window": "winter_to_winter",
"norms_set": "2025",
"rit_score": 239,
"achievement_percentile": 91,
"growth_percentile": 43,
"observed_growth": 6,
"projected_growth": 7,
"growth_x": 0.8571,
"growth_x_target": 2,
"on_track": false,
"sitting_count": 2,
"retake_count": 1,
"source_import_id": "imp_01HT8MAP_2026_WINTER",
"quality_status": "ok",
"modified_at": "2026-05-14T19:00:00Z"
}
],
"hasMore": false,
"nextCursor": null,
"links": {
"self": "/alpha/analytics/v1/map-growth-rollups"
}
}GET
/alpha/analytics/v1/norms
Read the versioned achievement-status norms resource that powers percentile-to-RIT and RIT-to-percentile translation. Same contract as /norms/table; cache by table_version and never ship a private norms table.
| Name | Type | Required | Description |
|---|---|---|---|
subject | subject_id enum | Optional | math, reading, language, or science. subjectId is accepted as an alias. |
grade | TEXT | Optional | K or 1 through 12. gradeLevel is accepted as an alias. |
season | TEXT enum | Optional | fall, winter, or spring. termSeason is accepted as an alias. |
role | TEXT | Optional | NWEA role/population label. Defaults to student for public student translations. |
normsSet | norms_set enum | Optional | 2020 or 2025. Omit to list both published sets. |
limit | INTEGER | Optional | Page size. Default 100; maximum 1000. |
cursor | TEXT | Optional | Opaque next-page cursor. |
| Field | Type | Nullability | Meaning | Source |
|---|---|---|---|---|
object | TEXT | required | Always list. | dictionary |
table | TEXT | required | analytics.norms_table list resource over alpha.analytics_norms_achievement. | dictionary |
table_version | TEXT | required | Version of the readable norms table. | dictionary |
data[].id | TEXT | required | Stable Analytics id for this norms row. | dictionary |
data[].norms_set | TEXT enum | required | Norms family for the row. | dictionary |
data[].subject_id | TEXT | required | Canonical subject for the norms row. | dictionary |
data[].source_subject_name | TEXT | required | Published source subject name for audit display. | dictionary |
data[].role | TEXT | required | NWEA role/population label for the row. | dictionary |
data[].grade_key | TEXT | required | NWEA grade key for the row. | dictionary |
data[].grade_level | INTEGER | required | Numeric grade level for sorting and display. | dictionary |
data[].season | TEXT | required | MAP testing season for the row. | dictionary |
data[].mean_rit | NUMERIC(7,2) | required | Published mean RIT for the row. | dictionary |
data[].sd_rit | NUMERIC(6,3) | required | Published RIT standard deviation for the row. | dictionary |
data[].calculator_version | TEXT | required | Version of the surface norms calculator/table. | dictionary |
data[].source_ref | TEXT | required | Opaque provenance pointer to NWEA-published norms. | dictionary |
limit | INTEGER | required | Rows returned in this page. | dictionary |
hasMore | BOOLEAN | required | Whether another page exists. | dictionary |
nextCursor | TEXT nullable | required | Opaque cursor for the next page. | dictionary |
links.self | URL | required | The request URL for this page. | dictionary |
curl -sS "$ANALYTICS_BASE_URL/alpha/analytics/v1/norms?subject=math&grade=5&season=winter&normsSet=2025&limit=1" \
-H "Authorization: Bearer $ANALYTICS_TOKEN"const response = await fetch(`${base}/alpha/analytics/v1/norms`, { headers: { Authorization: `Bearer ${token}` } });
if (!response.ok) throw await response.json();
const body = await response.json();{
"object": "list",
"table": "analytics.norms_table",
"table_version": "analytics.norms.achievement.v2026-06-12",
"data": [
{
"id": "norms_2025_math_student_5_winter",
"norms_set": "2025",
"subject_id": "math",
"source_subject_name": "Math",
"role": "student",
"grade_key": "5",
"grade_level": 5,
"season": "winter",
"mean_rit": 211.82,
"sd_rit": 17.42,
"calculator_version": "analytics.norms.achievement.v2026-06-12",
"source_ref": "NWEA 2025 MAP Growth Norms Technical Manual (Hawthorne, Velazquez, Peng, Hall, Newburn, 2025)"
}
],
"limit": 1,
"hasMore": false,
"nextCursor": null,
"links": {
"self": "/alpha/analytics/v1/norms?subject=math&grade=5&season=winter&normsSet=2025&limit=1"
}
}GET
/alpha/analytics/v1/norms/table
Read the paginated table rows for the current or requested NWEA achievement-status norms table version.
| Name | Type | Required | Description |
|---|---|---|---|
subject | subject_id enum | Optional | math, reading, language, or science. subjectId is accepted as an alias. |
grade | TEXT | Optional | K or 1 through 12. gradeLevel is accepted as an alias. |
season | TEXT enum | Optional | fall, winter, or spring. termSeason is accepted as an alias. |
role | TEXT | Optional | NWEA role/population label. Defaults to student for public student translations. |
normsSet | norms_set enum | Optional | 2020 or 2025. Omit to list both published sets. |
limit | INTEGER | Optional | Page size. Default 100; maximum 1000. |
cursor | TEXT | Optional | Opaque next-page cursor. |
| Field | Type | Nullability | Meaning | Source |
|---|---|---|---|---|
object | TEXT | required | Always list. | dictionary |
table | TEXT | required | analytics.norms_table list resource over alpha.analytics_norms_achievement. | dictionary |
table_version | TEXT | required | Version of the readable norms table. | dictionary |
data[].id | TEXT | required | Stable Analytics id for this norms row. | dictionary |
data[].norms_set | TEXT enum | required | Norms family for the row. | dictionary |
data[].subject_id | TEXT | required | Canonical subject for the norms row. | dictionary |
data[].source_subject_name | TEXT | required | Published source subject name for audit display. | dictionary |
data[].role | TEXT | required | NWEA role/population label for the row. | dictionary |
data[].grade_key | TEXT | required | NWEA grade key for the row. | dictionary |
data[].grade_level | INTEGER | required | Numeric grade level for sorting and display. | dictionary |
data[].season | TEXT | required | MAP testing season for the row. | dictionary |
data[].mean_rit | NUMERIC(7,2) | required | Published mean RIT for the row. | dictionary |
data[].sd_rit | NUMERIC(6,3) | required | Published RIT standard deviation for the row. | dictionary |
data[].calculator_version | TEXT | required | Version of the surface norms calculator/table. | dictionary |
data[].source_ref | TEXT | required | Opaque provenance pointer to NWEA-published norms. | dictionary |
limit | INTEGER | required | Rows returned in this page. | dictionary |
hasMore | BOOLEAN | required | Whether another page exists. | dictionary |
nextCursor | TEXT nullable | required | Opaque cursor for the next page. | dictionary |
links.self | URL | required | The request URL for this page. | dictionary |
curl -sS "$ANALYTICS_BASE_URL/alpha/analytics/v1/norms/table?subject=math&grade=5&season=winter&normsSet=2025&limit=1" \
-H "Authorization: Bearer $ANALYTICS_TOKEN"const response = await fetch(`${base}/alpha/analytics/v1/norms/table`, { headers: { Authorization: `Bearer ${token}` } });
if (!response.ok) throw await response.json();
const body = await response.json();{
"object": "list",
"table": "analytics.norms_table",
"table_version": "analytics.norms.achievement.v2026-06-12",
"data": [
{
"id": "norms_2025_math_student_5_winter",
"norms_set": "2025",
"subject_id": "math",
"source_subject_name": "Math",
"role": "student",
"grade_key": "5",
"grade_level": 5,
"season": "winter",
"mean_rit": 211.82,
"sd_rit": 17.42,
"calculator_version": "analytics.norms.achievement.v2026-06-12",
"source_ref": "NWEA 2025 MAP Growth Norms Technical Manual (Hawthorne, Velazquez, Peng, Hall, Newburn, 2025)"
}
],
"limit": 1,
"hasMore": false,
"nextCursor": null,
"links": {
"self": "/alpha/analytics/v1/norms/table?subject=math&grade=5&season=winter&normsSet=2025&limit=1"
}
}GET
/alpha/analytics/v1/norms/rit
Convert a requested achievement percentile to a RIT score using the surface-owned achievement norms table for subject, grade, season, role, and norms set.
| Name | Type | Required | Description |
|---|---|---|---|
subject | subject_id enum | Required | math, reading, language, or science. subjectId is accepted as an alias. |
grade | TEXT | Required | K or 1 through 12. gradeLevel is accepted as an alias. |
season | TEXT enum | Required | fall, winter, or spring. termSeason is accepted as an alias. |
role | TEXT | Optional | NWEA role/population label. Defaults to student. |
percentile | NUMERIC | Required | Percentile to translate. Must be greater than 0 and less than 100. |
normsSet | norms_set enum | Required | 2020 or 2025. |
| Field | Type | Nullability | Meaning | Source |
|---|---|---|---|---|
object | TEXT | required | analytics.norms_rit_translation. | dictionary |
direction | TEXT enum | required | percentile_to_rit. | dictionary |
subject_id | TEXT | required | Canonical subject used for the lookup. | dictionary |
grade_key | TEXT | required | Grade key used by the published norms resource. | dictionary |
grade_level | INTEGER | required | Numeric grade level used by the calculator. | dictionary |
season | TEXT | required | fall, winter, spring, or another published NWEA season label. | dictionary |
role | TEXT | required | NWEA role/population label used for the lookup. | dictionary |
percentile | NUMERIC(5,2) | required | Requested percentile. | dictionary |
rit_score | NUMERIC | required | Rounded RIT score returned by the surface calculator. | dictionary |
output_rit | NUMERIC | required | Stable output alias for the rounded RIT score. | dictionary |
raw_rit | NUMERIC | required | Unrounded calculator output, rounded to three decimals. | dictionary |
norms_set | TEXT enum | required | Norms family used for the lookup. | dictionary |
calculator_version | TEXT | required | Version of the surface norms table and calculator used for the normal-model translation. | dictionary |
mean_rit | NUMERIC(7,2) | required | Published mean RIT used by the calculator. | dictionary |
sd_rit | NUMERIC(6,3) | required | Published RIT standard deviation used by the calculator. | dictionary |
source_ref | TEXT | required | Provenance pointer for the published norms row. | dictionary |
links.table | URL | required | The /norms/table resource row used for the lookup. | dictionary |
curl -sS "$ANALYTICS_BASE_URL/alpha/analytics/v1/norms/rit?subject=math&grade=5&season=winter&percentile=99&normsSet=2025" \
-H "Authorization: Bearer $ANALYTICS_TOKEN"const response = await fetch(`${base}/alpha/analytics/v1/norms/rit`, { headers: { Authorization: `Bearer ${token}` } });
if (!response.ok) throw await response.json();
const body = await response.json();{
"object": "analytics.norms_rit_translation",
"direction": "percentile_to_rit",
"norms_set": "2025",
"subject_id": "math",
"grade_key": "5",
"grade_level": 5,
"season": "winter",
"role": "student",
"percentile": 99,
"rit_score": 252,
"output_rit": 252,
"raw_rit": 252.345,
"calculator_version": "analytics.norms.achievement.v2026-06-12",
"mean_rit": 211.82,
"sd_rit": 17.42,
"source_ref": "NWEA 2025 MAP Growth Norms Technical Manual (Hawthorne, Velazquez, Peng, Hall, Newburn, 2025)",
"links": {
"table": "/alpha/analytics/v1/norms/table?subject=math&grade=5&season=winter&normsSet=2025&role=student"
}
}GET
/alpha/analytics/v1/norms/percentile
Convert a RIT score to an achievement percentile using the same surface-owned norms table row.
| Name | Type | Required | Description |
|---|---|---|---|
subject | subject_id enum | Required | math, reading, language, or science. subjectId is accepted as an alias. |
grade | TEXT | Required | K or 1 through 12. gradeLevel is accepted as an alias. |
season | TEXT enum | Required | fall, winter, or spring. termSeason is accepted as an alias. |
role | TEXT | Optional | NWEA role/population label. Defaults to student. |
rit | NUMERIC | Required | RIT score to translate. |
normsSet | norms_set enum | Required | 2020 or 2025. |
| Field | Type | Nullability | Meaning | Source |
|---|---|---|---|---|
object | TEXT | required | analytics.norms_percentile_translation. | dictionary |
direction | TEXT enum | required | rit_to_percentile. | dictionary |
subject_id | TEXT | required | Canonical subject used for the lookup. | dictionary |
grade_key | TEXT | required | Grade key used by the published norms resource. | dictionary |
grade_level | INTEGER | required | Numeric grade level used by the calculator. | dictionary |
season | TEXT | required | fall, winter, spring, or another published NWEA season label. | dictionary |
role | TEXT | required | NWEA role/population label used for the lookup. | dictionary |
rit_score | NUMERIC | required | Requested RIT score, rounded for response stability. | dictionary |
input_rit | NUMERIC | required | Requested RIT score. | dictionary |
percentile | NUMERIC(5,2) | required | Achievement percentile returned by the surface calculator. | dictionary |
output_percentile | NUMERIC(5,2) | required | Stable output alias for the achievement percentile. | dictionary |
raw_percentile | NUMERIC | required | Unrounded normal-model percentile, rounded to three decimals. | dictionary |
norms_set | TEXT enum | required | Norms family used for the lookup. | dictionary |
calculator_version | TEXT | required | Version of the surface norms table and calculator used for the normal-model translation. | dictionary |
mean_rit | NUMERIC(7,2) | required | Published mean RIT used by the calculator. | dictionary |
sd_rit | NUMERIC(6,3) | required | Published RIT standard deviation used by the calculator. | dictionary |
source_ref | TEXT | required | Provenance pointer for the published norms row. | dictionary |
links.table | URL | required | The /norms/table resource row used for the lookup. | dictionary |
curl -sS "$ANALYTICS_BASE_URL/alpha/analytics/v1/norms/percentile?subject=math&grade=5&season=winter&rit=247&normsSet=2025" \
-H "Authorization: Bearer $ANALYTICS_TOKEN"const response = await fetch(`${base}/alpha/analytics/v1/norms/percentile`, { headers: { Authorization: `Bearer ${token}` } });
if (!response.ok) throw await response.json();
const body = await response.json();{
"object": "analytics.norms_percentile_translation",
"direction": "rit_to_percentile",
"norms_set": "2025",
"subject_id": "math",
"grade_key": "5",
"grade_level": 5,
"season": "winter",
"role": "student",
"rit_score": 247,
"input_rit": 247,
"percentile": 98,
"output_percentile": 98,
"raw_percentile": 97.828,
"calculator_version": "analytics.norms.achievement.v2026-06-12",
"mean_rit": 211.82,
"sd_rit": 17.42,
"source_ref": "NWEA 2025 MAP Growth Norms Technical Manual (Hawthorne, Velazquez, Peng, Hall, Newburn, 2025)",
"links": {
"table": "/alpha/analytics/v1/norms/table?subject=math&grade=5&season=winter&normsSet=2025&role=student"
}
}GET
/alpha/analytics/v1/r90/table
Read the single versioned Alpha R90 table used for RIT-to-grade and GOALS track-position work.
| Name | Type | Required | Description |
|---|---|---|---|
subject | subject_id enum | Optional | math, reading, language, science, or a locked proxy subject such as vocabulary, writing, or fastmath. subjectId is accepted as an alias. |
normsSet | norms_set enum | Optional | 2020 or 2025. Accepted for caller symmetry; the current R90 table version is returned. |
tableVersion | TEXT | Optional | Immutable R90 table_version. Omit for the current version of the requested normsSet. |
limit | INTEGER | Optional | Page size. Default 100; maximum 1000. |
cursor | TEXT | Optional | Opaque next-page cursor. |
| Field | Type | Nullability | Meaning | Source |
|---|---|---|---|---|
object | TEXT | required | Always list. | dictionary |
table | TEXT | required | analytics.r90_table list resource over alpha.analytics_r90_table. | dictionary |
table_version | TEXT | required | Version of the readable R90 table. | dictionary |
data[].id | TEXT | required | Stable Analytics id for this R90 row. | dictionary |
data[].table_version | TEXT | required | Immutable version id for the row. | dictionary |
data[].table_subject_id | TEXT | required | Canonical table subject for this R90 row. | dictionary |
data[].subject_id | TEXT | required | Subject returned by the table endpoint. | dictionary |
data[].source_subject_name | TEXT | required | Published source subject name for audit display. | dictionary |
data[].rit_score | NUMERIC(7,2) | required | RIT score represented by this row. | dictionary |
data[].r90_grade | TEXT | required | Plain grade-position value for this row. | dictionary |
data[].effective_grade | TEXT | required | Report-ready grade/effective-grade label. | dictionary |
data[].r90_grade_level | TEXT | required | Governed grade-level bucket for this row. | dictionary |
data[].r90_percent_complete | NUMERIC(7,3) | required | Compatibility field for the MAP-inferred percent through the R90 grade band. | dictionary |
data[].rit90_grade_band_percent | NUMERIC(7,3) | required | Clear field name for the MAP-inferred percent through the R90 grade band. This is not actual course or grade-level progress. | dictionary |
data[].observation_count | INTEGER | required | Count carried by the Alpha R90 mirror for audit. | dictionary |
data[].source_ref | TEXT | required | Runtime provenance pointer for the NWEAMAP-owned seeded grade2rit source backing this current table row. It is not a route and clients do not read it to answer reports; cache and reproduce by table_version. | dictionary |
limit | INTEGER | required | Rows returned in this page. | dictionary |
hasMore | BOOLEAN | required | Whether another page exists. | dictionary |
nextCursor | TEXT nullable | required | Opaque cursor for the next page. | dictionary |
links.self | URL | required | The request URL for this page. | dictionary |
curl -sS "$ANALYTICS_BASE_URL/alpha/analytics/v1/r90/table?subject=math&normsSet=2025&limit=1" \
-H "Authorization: Bearer $ANALYTICS_TOKEN"const response = await fetch(`${base}/alpha/analytics/v1/r90/table`, { headers: { Authorization: `Bearer ${token}` } });
if (!response.ok) throw await response.json();
const body = await response.json();{
"object": "list",
"table": "analytics.r90_table",
"table_version": "analytics.rit_to_grade.powerpath.v2026-06-15",
"data": [
{
"id": "r90_math_172",
"table_version": "analytics.rit_to_grade.powerpath.v2026-06-15",
"table_subject_id": "math",
"subject_id": "math",
"source_subject_name": "Math",
"rit_score": 172,
"r90_grade": 0,
"effective_grade": 1,
"r90_grade_level": 0,
"r90_percent_complete": 0,
"rit90_grade_band_percent": 0,
"observation_count": 1,
"source_ref": "powerpath:/powerpath/rit-to-grade",
"ownerModule": "nweamap"
}
],
"limit": 1,
"hasMore": true,
"nextCursor": "eyJvZmZzZXQiOjF9",
"links": {
"self": "/alpha/analytics/v1/r90/table?subject=math&normsSet=2025&limit=1"
}
}GET
/alpha/analytics/v1/r90
Return the R90 grade, effective grade, grade level, and MAP-inferred grade-band percent for a RIT score using the current exact PowerPath RIT-to-grade mirror.
| Name | Type | Required | Description |
|---|---|---|---|
subject | subject_id enum | Required | math, reading, language, science, or a locked proxy subject such as vocabulary, writing, or fastmath. subjectId is accepted as an alias. |
rit | NUMERIC | Required | RIT score to translate. Exact table hits return source_point_kind=exact; missing rows return source_point_kind=source_missing rather than interpolation, step-flooring, upward clamping, or extrapolation. |
normsSet | norms_set enum | Optional | 2020 or 2025. Accepted for caller symmetry; R90 table_version is returned in the body. |
tableVersion | TEXT | Optional | Immutable R90 table_version. Omit for the current version of the requested normsSet. |
| Field | Type | Nullability | Meaning | Source |
|---|---|---|---|---|
object | TEXT | required | analytics.r90_lookup. | dictionary |
table_version | TEXT | required | Version of the Alpha R90 mirror table. | dictionary |
requested_subject_id | TEXT | required | Subject requested by the caller before locked proxy folding. | dictionary |
table_subject_id | TEXT | required | Canonical table subject used for the lookup. | dictionary |
subject_id | TEXT | required | Subject returned to the caller after validation. | dictionary |
rit_score | NUMERIC | required | RIT table point used for the response. | dictionary |
table_rit_score | NUMERIC nullable | required | Selected table RIT. Exact lookups return the current-version row whose rit_score equals the requested RIT; missing rows return source_missing. | dictionary |
r90_grade | TEXT | required | Plain grade-position value for the RIT row. | dictionary |
effective_grade | TEXT | required | Report-ready grade/effective-grade label. | dictionary |
r90_grade_level | TEXT | required | Governed grade-level bucket for this R90 row. | dictionary |
r90_percent_complete | NUMERIC(7,3) | required | Compatibility field for the MAP-inferred percent through the R90 grade band. | dictionary |
rit90_grade_band_percent | NUMERIC(7,3) | required | Clear field name for the MAP-inferred percent through the R90 grade band. This is not actual course or grade-level progress. | dictionary |
source_point_kind | TEXT enum | required | exact or source_missing. The current R90 lookup never interpolates, step-floors, clamps, or extrapolates. | dictionary |
calculator_version | TEXT | required | Version of the Alpha R90 mirror table and calculator. | dictionary |
source_ref | TEXT | required | Runtime provenance pointer for the NWEAMAP-owned seeded grade2rit source row used by this lookup. It is not a route and clients do not read it to answer reports; cache and reproduce by table_version. | dictionary |
links.table | URL | required | The /r90/table resource family used for the lookup. | dictionary |
curl -sS "$ANALYTICS_BASE_URL/alpha/analytics/v1/r90?subject=math&rit=239&normsSet=2025" \
-H "Authorization: Bearer $ANALYTICS_TOKEN"const response = await fetch(`${base}/alpha/analytics/v1/r90`, { headers: { Authorization: `Bearer ${token}` } });
if (!response.ok) throw await response.json();
const body = await response.json();{
"object": "analytics.r90_lookup",
"table_version": "analytics.rit_to_grade.powerpath.v2026-06-15",
"requested_subject_id": "math",
"table_subject_id": "math",
"subject_id": "math",
"rit_score": 239,
"table_rit_score": 239,
"r90_grade": 4.8,
"effective_grade": 5,
"r90_grade_level": 4,
"r90_percent_complete": 80,
"rit90_grade_band_percent": 80,
"source_point_kind": "exact",
"calculator_version": "analytics.rit_to_grade.powerpath.v2026-06-15",
"source_ref": "powerpath:/powerpath/rit-to-grade",
"ownerModule": "nweamap",
"links": {
"table": "/alpha/analytics/v1/r90/table?subject=math"
}
}GET
/alpha/analytics/v1/school-days-remaining
Return the forward instructional-day count and XP-to-time effort projection GOALS needs for its target-date column. GOALS asks Analytics for this read instead of doing calendar arithmetic locally.
| Name | Type | Required | Description |
|---|---|---|---|
studentId | TEXT | Required | Canonical Alpha student id. |
schoolId | TEXT | Optional | School id for the calendar denominator. Omit to let Analytics infer the student's enrolled school. |
asOf | DATE | Required | Start date for the forward school-day count. startDate is accepted as an alias. |
endDate | DATE | Optional | Exclusive end date for the forward window. schoolYearEnd is accepted as an alias; omit to use the surface's current GOALS school-year end. |
targetDate | DATE | Optional | Date GOALS wants to test for the target-date column. Must be after asOf and on or before endDate. |
xpRemaining | NUMERIC | Optional | Remaining XP to convert into expected minutes by the surface unit 1 XP = 1 expected minute. Mutually exclusive with minutesRemaining and hoursRemaining. |
minutesRemaining | NUMERIC | Optional | Expected minutes remaining. Mutually exclusive with xpRemaining and hoursRemaining. |
hoursRemaining | NUMERIC | Optional | Expected hours remaining. Mutually exclusive with xpRemaining and minutesRemaining. |
hoursPerSchoolDay | NUMERIC | Optional | Planned hours per instructional day. When present, Analytics returns how many school days are needed and the date reached at that pace. |
| Field | Type | Nullability | Meaning | Source |
|---|---|---|---|---|
object | TEXT | required | analytics.school_days_remaining. | dictionary |
student_id | TEXT | required | Canonical Alpha student id used for the calendar/enrollment lookup. | dictionary |
school_id | TEXT | required | School id whose alpha.school_calendar rows were read. | dictionary |
as_of | DATE | required | Inclusive start date for the forward count. | dictionary |
end_date | DATE | required | Exclusive end date for the forward count. | dictionary |
school_day_policy_ref | TEXT | required | Policy ref used to decide which calendar dates count as instructional days and which MAP days are excluded. | dictionary |
instructional_days_remaining | INTEGER | required | Count of school days after applying alpha.policy.school_day over the half-open [asOf, endDate) window. | dictionary |
calendar_ref_count | INTEGER | required | Count of calendar rows inspected before filtering to instructional days. | dictionary |
first_instructional_date | DATE nullable | required | First remaining instructional day, or null when no school day remains. | dictionary |
last_instructional_date | DATE nullable | required | Last remaining instructional day in the requested window. | dictionary |
instructional_dates | DATE[] | required | Instructional dates in the requested window. Render or cache these only as the surface-returned answer; do not recreate them from a private calendar. | dictionary |
xp_unit.policy_ref | TEXT | required | Versioned policy that defines XP-to-expected-minute conversion. | dictionary |
xp_unit.xp_per_expected_minute | NUMERIC | required | Surface-owned unit convention: 1 XP equals 1 expected minute. | dictionary |
xp_unit.xp_per_hour | NUMERIC | required | Surface-owned conversion: 60 XP equals one expected hour. | dictionary |
xp_unit.meaning | TEXT | required | Plain-language statement of the XP time conversion. | dictionary |
effort.xp_remaining | NUMERIC nullable | required | Caller-supplied remaining XP when xpRemaining was used. | dictionary |
effort.expected_minutes_remaining | NUMERIC nullable | required | Remaining effort in expected minutes after applying the surface XP/minutes/hours conversion. | dictionary |
effort.hours_remaining | NUMERIC nullable | required | Remaining effort in hours. | dictionary |
effort.target_date | DATE nullable | required | Requested target date, if supplied. | dictionary |
effort.school_days_until_target_date | INTEGER nullable | required | Instructional days between asOf and targetDate. | dictionary |
effort.required_hours_per_school_day_to_target_date | NUMERIC nullable | required | Hours per remaining school day needed to finish by targetDate. | dictionary |
effort.hours_per_school_day | NUMERIC nullable | required | Caller-supplied pace assumption. | dictionary |
effort.school_days_needed_at_hours_per_school_day | INTEGER nullable | required | Instructional days needed at the supplied pace. | dictionary |
effort.target_date_at_hours_per_school_day | DATE nullable | required | Instructional date reached at the supplied pace, or null when the window is too short. | dictionary |
effort.can_finish_by_end_date_at_hours_per_school_day | BOOLEAN nullable | required | Whether the supplied pace finishes within the requested forward window. | dictionary |
provenance.source | TEXT | required | Calendar source read by Analytics. | dictionary |
provenance.source_ref_sample | TEXT[] | required | Sample Ed-Fi CalendarDate-derived refs used for audit. | dictionary |
provenance.policy_ref | TEXT | required | Policy ref used for the school-day decision. | dictionary |
provenance.xp_unit_policy_ref | TEXT | required | XP expected-minute policy ref used for effort projection. | dictionary |
links.self | URL | required | The request URL for this read. | dictionary |
links.schoolDayMinutes | URL | required | Related school-day-minutes rollup endpoint. | dictionary |
links.xpRollups | URL | required | Related XP rollup endpoint. | dictionary |
curl -sS "$ANALYTICS_BASE_URL/alpha/analytics/v1/school-days-remaining?studentId=student-ada-001&asOf=2026-06-14&endDate=2026-07-24&xpRemaining=600&hoursPerSchoolDay=1.5&targetDate=2026-07-24" \
-H "Authorization: Bearer $ANALYTICS_TOKEN"const response = await fetch(`${base}/alpha/analytics/v1/school-days-remaining`, { headers: { Authorization: `Bearer ${token}` } });
if (!response.ok) throw await response.json();
const body = await response.json();{
"object": "analytics.school_days_remaining",
"student_id": "student-ada-001",
"school_id": "school_alpha_demo",
"as_of": "2026-06-14",
"end_date": "2026-07-24",
"school_day_policy_ref": "alpha.policy.school_day.v2026-06-10",
"instructional_days_remaining": 29,
"calendar_ref_count": 40,
"first_instructional_date": "2026-06-15",
"last_instructional_date": "2026-07-23",
"instructional_dates": [
"2026-06-15",
"2026-06-16",
"2026-06-17"
],
"xp_unit": {
"policy_ref": "alpha.policy.analytics.xp_expected_minute.v2026-06-14",
"xp_per_expected_minute": 1,
"xp_per_hour": 60,
"meaning": "1 XP = 1 expected minute; XP hours = XP / 60."
},
"effort": {
"xp_remaining": 600,
"expected_minutes_remaining": 600,
"hours_remaining": 10,
"target_date": "2026-07-24",
"school_days_until_target_date": 29,
"required_hours_per_school_day_to_target_date": 0.345,
"hours_per_school_day": 1.5,
"school_days_needed_at_hours_per_school_day": 7,
"target_date_at_hours_per_school_day": "2026-06-23",
"can_finish_by_end_date_at_hours_per_school_day": true
},
"provenance": {
"source": "alpha.school_calendar",
"source_ref_sample": [
"ed_fi.CalendarDate:school_alpha_demo:2026-06-15"
],
"policy_ref": "alpha.policy.school_day.v2026-06-10",
"xp_unit_policy_ref": "alpha.policy.analytics.xp_expected_minute.v2026-06-14"
},
"links": {
"self": "/alpha/analytics/v1/school-days-remaining?studentId=student-ada-001&asOf=2026-06-14&endDate=2026-07-24",
"schoolDayMinutes": "/alpha/analytics/v1/school-day-minutes?studentId=student-ada-001",
"xpRollups": "/alpha/analytics/v1/xp-rollups?studentId=student-ada-001&windowKind=school_year"
}
}GET
/alpha/analytics/v1/grade-level-status
Return the two named GOALS age-grade comparisons. Analytics reads P&O age grade and Results grade positions, then returns working-vs-age and mastered-vs-age labels so clients do not recompute or rename ahead/at/behind.
| Name | Type | Required | Description |
|---|---|---|---|
studentId | TEXT | Required | Canonical Alpha student id. |
subject | subject_id enum | Required | Canonical subject id. subjectId is also accepted by the runtime. |
asOfDate | DATE | Required | Point-in-time date for P&O age grade and Results grade state. |
| Field | Type | Nullability | Meaning | Source |
|---|---|---|---|---|
object | TEXT | required | analytics.grade_level_status. | dictionary |
student_id | TEXT | required | Canonical Alpha student id. | dictionary |
subject_id | TEXT | required | Canonical subject id used for Results working/HMG lookup. | dictionary |
as_of_date | DATE | required | Point-in-time date for P&O age grade and Results state. | dictionary |
age_grade | INTEGER nullable | required | School-assigned cohort grade from People & Orgs alpha.age_grade_history. | dictionary |
working_grade | INTEGER nullable | required | Results-owned working grade. | dictionary |
highest_mastered_grade | INTEGER nullable | required | Results-owned highest mastered grade. | dictionary |
working_age_grade_delta | INTEGER nullable | required | working_grade - age_grade. | dictionary |
working_age_grade_status | TEXT enum | required | working_behind_age_grade, working_at_age_grade, working_above_age_grade, or unknown. | dictionary |
mastered_age_grade_delta | INTEGER nullable | required | highest_mastered_grade - age_grade. | dictionary |
mastered_age_grade_status | TEXT enum | required | mastered_behind_age_grade, mastered_at_age_grade, mastered_above_age_grade, or unknown. | dictionary |
source_refs | JSON object | required | Owner pointers for P&O age grade and Results grade positions. | dictionary |
deprecated_aliases | JSON object | required | Compatibility mapping only; not the preferred public contract. | dictionary |
curl -sS "$ANALYTICS_BASE_URL/alpha/analytics/v1/grade-level-status?studentId=b6fa7128-f641-4efd-9075-375411fd6c39&subject=math&asOfDate=2026-05-20" \
-H "Authorization: Bearer $ANALYTICS_TOKEN"const response = await fetch(`${base}/alpha/analytics/v1/grade-level-status`, { headers: { Authorization: `Bearer ${token}` } });
if (!response.ok) throw await response.json();
const body = await response.json();{
"object": "analytics.grade_level_status",
"student_id": "b6fa7128-f641-4efd-9075-375411fd6c39",
"subject_id": "math",
"as_of_date": "2026-05-20",
"age_grade": 5,
"working_grade": 6,
"highest_mastered_grade": 5,
"working_age_grade_delta": 1,
"working_age_grade_status": "working_above_age_grade",
"mastered_age_grade_delta": 0,
"mastered_age_grade_status": "mastered_at_age_grade",
"source_refs": {
"age_grade": "people_and_orgs.alpha.age_grade_history",
"working_grade": "results.student_track_state.working_grade",
"highest_mastered_grade": "results.highest_mastered_grade"
},
"deprecated_aliases": {
"instructional_level_status": "working_age_grade_status",
"strict_mastery_status": "mastered_age_grade_status"
}
}GET
/alpha/analytics/v1/completion-rollups
Read progress evidence used by Results and audit views. Course rows preserve app-reported Caliper percent and XP remaining evidence; student-facing course and grade-level progress comes from Results course-progress and grade-level-progress.
| Name | Type | Required | Description |
|---|---|---|---|
studentId | TEXT | Optional | Canonical Alpha student id. |
completionScope | completion_scope enum | Optional | course, subject, track, track_level, grade_level, or segment. |
scopeId | TEXT | Optional | Course, subject, track, track-level, grade-level, or segment scope id. Grade-level scope ids are grade_level:{subject}:{grade}. |
subjectId | subject_id enum | Optional | Canonical Alpha subject id. |
startDate | DATE | Optional | Inclusive reporting window start. |
endDate | DATE | Optional | Exclusive reporting window end. |
modifiedSince | TIMESTAMPTZ | Optional | Poll for changed rows. |
limit | INTEGER | Optional | Page size. Default 100; maximum 1000. |
cursor | TEXT | Optional | Opaque next-page cursor. |
| Field | Type | Nullability | Meaning | Source |
|---|---|---|---|---|
id | UUID | required | Analytics-owned stable row id for this derived fact. Generated by the platform; globally unique within alpha.analytics_* objects. | dictionary |
student_id | TEXT | required | Canonical Alpha student id the source Event or Result resolved to at materialization time. Must resolve through People and Orgs as a real student for the source timestamp/effective date. | dictionary |
completion_scope | TEXT enum | required | Curriculum/reporting scope for this completion measure. Allowed values: completion_scope enum. | dictionary |
scope_id | TEXT | required | Identifier of the Curriculum or subject scope being measured. Must match completion_scope: course id for course, subject id for subject, track id for track, etc. | dictionary |
subject_id | TEXT | nullable; required when completion_scope=subject or the scope resolves to one subject | Canonical Alpha subject used for reporting and grouping. Closed Alpha subject enum after write-time alias folds; unknown source subject becomes an adapter finding or null_reason, not a new string. | dictionary |
grade_level | INTEGER | nullable for non-grade-level scopes without a course grade | Working grade level associated with the course progress row, or the grade represented by a grade_level aggregate. Must come from the course/Caliper/Curriculum scope metadata, not from MAP/RIT/R90. | dictionary |
is_main_course | BOOLEAN | nullable when not applicable; true for main course and grade_level aggregate rows | Whether the course row counts toward grade-level progress. Main grade-level courses count; remediation, hole-filling, catalog, practice, and review courses do not. | dictionary |
progress_source_kind | TEXT enum | required for reportable progress rows | Which evidence source produced completion_percent. Allowed values include app_reported_percent, xp_remaining, lesson_count, subject_aggregate, and main_course_aggregate. | dictionary |
xp_earned | NUMERIC(14,3) | nullable when progress_source_kind is app_reported_percent or an aggregate without XP evidence | Earned XP for this completion scope when the row uses the XP fallback. Nonnegative when present; source corrections are reflected through quality_status/corrections before this value is reportable. | dictionary |
xp_remaining | NUMERIC(14,3) | nullable when progress_source_kind is app_reported_percent or an aggregate without XP evidence | Remaining expected XP for this completion scope when the row uses the XP fallback. Nonnegative when present; computed from Curriculum expected XP refs under denominator_policy_ref. | dictionary |
completion_percent | NUMERIC(7,3) | nullable when no direct percent, XP denominator, lesson denominator, or source/policy is available | Report-ready completion measure for the scope. Direct app percent wins. If absent, fallback formula is xp_earned / (xp_earned + xp_remaining) * 100. Normally 0 to 100; null requires null_reason. | dictionary |
denominator_policy_ref | TEXT | required | Policy that decides which Curriculum expected-XP refs belong in the remaining-XP denominator. Named versioned progress policy, for example alpha.policy.analytics.course_progress.v2026-06-15 or alpha.policy.curriculum.main_course_grade_level.v2026-06-15, or inherited Curriculum policy. | dictionary |
curriculum_scope_refs | JSONB | required | Compact ids/cursor for Curriculum refs used to form the denominator. Refs/hashes only; never copies Curriculum trees or Content rows. | dictionary |
source_import_id | TEXT | required for report-tile rows; nullable for purely derived event-axis rows | Analytics source-import receipt that proves which named report-source adapter produced this report-grade fact. Must reference alpha.analytics_source_import for non-null Learning Report tile values; no literal or fixture value may be reportable without this provenance. | dictionary |
null_reason | TEXT enum | required | Why completion_percent is null or not reportable. Allowed values: null_reason enum; none means the metric is populated. | dictionary |
quality_status | TEXT enum | required | Current materialization quality state for this fact. Allowed values: quality_status enum. Ordinary report reads keep ok, corrected, and signed reversed rows according to the table rule; audit reads may include source_missing/source_unlinked/policy_pending/adapter_rejected. | dictionary |
modified_at | TIMESTAMPTZ | required | Last time the Analytics row changed for polling and modifiedSince queries. UTC timestamp; list endpoints support modifiedSince against this field. | dictionary |
curl -sS "$ANALYTICS_BASE_URL/alpha/analytics/v1/completion-rollups?studentId=student_01HT7G3YZV7QB5N4YKQ1K0Z9A9&completionScope=course&scopeId=course_math_grade_4_powerpath" \
-H "Authorization: Bearer $ANALYTICS_TOKEN"const response = await fetch(`${base}/alpha/analytics/v1/completion-rollups`, { headers: { Authorization: `Bearer ${token}` } });
if (!response.ok) throw await response.json();
const body = await response.json();{
"object": "list",
"url": "/alpha/analytics/v1/completion-rollups",
"data": [
{
"id": "6d7d3b01-6b70-44ce-90dd-e7cf2f690006",
"student_id": "student_01HT7G3YZV7QB5N4YKQ1K0Z9A9",
"completion_scope": "course",
"scope_id": "course_math_grade_4_powerpath",
"subject_id": "math",
"grade_level": 4,
"is_main_course": true,
"progress_source_kind": "app_reported_percent",
"xp_earned": null,
"xp_remaining": null,
"completion_percent": 75,
"denominator_policy_ref": "alpha.policy.analytics.course_progress.v2026-06-15",
"curriculum_scope_refs": [
"course_component_01HT8ROOT",
"progress_source:app_reported_percent",
"course_role:main",
"grade_level:4"
],
"source_import_id": "imp_01HT8COMPLETION_2026_SPRING",
"null_reason": "none",
"quality_status": "ok",
"modified_at": "2026-06-01T01:03:00Z"
}
],
"hasMore": false,
"nextCursor": null,
"links": {
"self": "/alpha/analytics/v1/completion-rollups"
}
}POST
/alpha/analytics/v1/source-imports/timeback-xp-time-accuracy
Submit source-shaped reporting.processed_facts rows. Analytics normalizes subject, time, XP, and source refs server-side.
| Name | Type | Required | Description |
|---|---|---|---|
Idempotency-Key | HTTP header | Required | Required for source imports. Same key plus different body returns analytics:idempotency_conflict. |
sourceBatchRef | TEXT | Required | Operator-controlled batch reference for audit and reconciliation. |
rows | JSON array | Required | Raw source-shaped processed_facts rows. Do not pre-normalize subject, time, XP, or student identity. |
| Field | Type | Nullability | Meaning | Source |
|---|---|---|---|---|
import_id | TEXT | required | Stable id for this source import request. Generated by platform; unique per tenant. | dictionary |
status | TEXT enum | required | Processing state of the source import. Allowed values: import_status enum. | dictionary |
submitted_row_count | INTEGER | required | Number of source-shaped rows submitted in the batch. Nonnegative. | dictionary |
accepted_row_count | INTEGER | required | Rows accepted by request validation and adapter mapping. Nonnegative and not greater than submitted_row_count. | dictionary |
materialized_row_count | INTEGER | required | Rows that produced readable Analytics facts. Nonnegative; successful nonempty imports must produce readable rows unless status explains otherwise. | dictionary |
rejected_row_count | INTEGER | required | Rows rejected by validation or adapter mapping. Nonnegative; submitted = accepted + rejected for completed imports. | dictionary |
problem_counts | JSONB | required | Counts of typed Problem codes produced by the import. Keys must be stable analytics:* codes; values nonnegative integers. | dictionary |
completed_at | TIMESTAMPTZ | nullable until processing completes | When import processing reached a terminal status. UTC timestamp; null while status is received/running. | dictionary |
curl -sS -X POST "$ANALYTICS_BASE_URL/alpha/analytics/v1/source-imports/timeback-xp-time-accuracy" \
-H "Authorization: Bearer $ANALYTICS_TOKEN" \
-H "Idempotency-Key: pfacts-demo-2026-05-01" \
-H "Content-Type: application/json" \
--data '{"sourceBatchRef":"migration-demo-2026-05","rows":[{"date":"2026-05-14","subject":"Math","app":"Math Academy","active_seconds":420,"inactive_seconds":0,"waste_seconds":0,"xp_earned":18}]}'const response = await fetch(`${base}/alpha/analytics/v1/source-imports/timeback-xp-time-accuracy`, { method: "POST", headers: { Authorization: `Bearer ${token}`, "Idempotency-Key": "demo-import-001", "Content-Type": "application/json" }, body: JSON.stringify({ sourceBatchRef: "demo", rows: [] }) });
if (!response.ok) throw await response.json();
const body = await response.json();{
"import_id": "import_01J0ANALYTICS",
"status": "materialized",
"submitted_row_count": 250,
"accepted_row_count": 249,
"materialized_row_count": 249,
"rejected_row_count": 1,
"problem_counts": {
"analytics:source_unlinked": 1
},
"completed_at": "2026-06-12T17:05:00Z"
}POST
/alpha/analytics/v1/source-imports/timeback-map
Submit source-shaped reporting.hp_map_results rows. Analytics normalizes student, subject, term, norms, test-of-record, Growth X, and R90 position server-side.
| Name | Type | Required | Description |
|---|---|---|---|
Idempotency-Key | HTTP header | Required | Required for source imports. Same key plus different body returns analytics:idempotency_conflict. |
sourceBatchRef | TEXT | Required | Operator-controlled batch reference for audit and reconciliation. |
rows | JSON array | Required | Full source-shaped reporting.hp_map_results rows. Submit the row as exported; do not pre-dedupe, parse terms, normalize subjects, compute Growth X, or apply norms/R90 locally. |
rows[].studentid | TEXT | Required | TimeBack/NWEA student id from hp_map_results. student_sourced_id is accepted only for migration compatibility; the adapter resolves the canonical Alpha student id. |
rows[].course or rows[].subject | TEXT | Required | Source MAP course/subject label such as Math K-12. The adapter writes the canonical subject_id. |
rows[].termname | TEXT | Required | Source MAP term label such as Winter 2025-2026. The adapter writes canonical_term_id; callers do not parse term strings. |
rows[].testritscore | INTEGER | Required | MAP RIT score. Missing RIT returns analytics:adapter_rejected. |
rows[].normsreferencedata | INTEGER enum | Required | NWEA norms family, normally 2020 or 2025. The adapter writes norms_set. |
rows[].wintertowinterobservedgrowth | NUMERIC | Required for winter_to_winter | Observed growth for the Learning Report MAP window. |
rows[].wintertowinterprojectedgrowth | NUMERIC | Required for winter_to_winter | Projected-growth denominator for Growth X. The adapter never uses typical growth as the Learning Report denominator when projected growth is present. |
rows[].testpercentile | INTEGER | Optional | Achievement percentile from hp_map_results. If omitted, Analytics derives it from the surface-owned norms table and stamps the calculator/table version. |
| Field | Type | Nullability | Meaning | Source |
|---|---|---|---|---|
import_id | TEXT | required | Stable id for this source import request. Generated by platform; unique per tenant. | dictionary |
import_kind | TEXT enum | required | Which source/replay contract this batch follows. Allowed values: import_kind enum. | dictionary |
adapter_name | TEXT | required | Named server-side adapter that normalized this source batch. Must match one approved adapter: timeback-xp-time-accuracy, timeback-map, timeback-grade-mastery, or timeback-completion, plus internal replay kinds where applicable. | dictionary |
source_system | TEXT | required | Producer system the adapter read from. Closed governed values for approved adapters: reporting, events, results, migration_reconcile. | dictionary |
source_table | TEXT | required for report-source adapters | Report-source table or producer collection read by the adapter. For the four public report adapters: processed_facts, hp_map_results, assessment_results, or processed_facts+courses+course_components. For timeback-map, source_table=hp_map_results means the adapter accepts the full source-shaped row and ignores unknown extra columns. | dictionary |
status | TEXT enum | required | Processing state of the source import. Allowed values: import_status enum. | dictionary |
submitted_row_count | INTEGER | required | Number of source-shaped rows submitted in the batch. Nonnegative. | dictionary |
accepted_row_count | INTEGER | required | Rows accepted by request validation and adapter mapping. Nonnegative and not greater than submitted_row_count. | dictionary |
materialized_row_count | INTEGER | required | Rows that produced readable Analytics facts. Nonnegative; successful nonempty imports must produce readable rows unless status explains otherwise. | dictionary |
rejected_row_count | INTEGER | required | Rows rejected by validation or adapter mapping. Nonnegative; submitted = accepted + rejected for completed imports. | dictionary |
problem_counts | JSONB | required | Counts of typed Problem codes produced by the import. Keys must be stable analytics:* codes; values nonnegative integers. | dictionary |
completed_at | TIMESTAMPTZ | nullable until processing completes | When import processing reached a terminal status. UTC timestamp; null while status is received/running. | dictionary |
curl -sS -X POST "$ANALYTICS_BASE_URL/alpha/analytics/v1/source-imports/timeback-map" \
-H "Authorization: Bearer $ANALYTICS_TOKEN" \
-H "Idempotency-Key: hp-map-demo-2026-winter" \
-H "Content-Type: application/json" \
--data '{"sourceBatchRef":"migration-demo-map-2026-winter","rows":[{"id":"hp-map-demo-001","studentid":"student_01HT7G3YZV7QB5N4YKQ1K0Z9A9","course":"Math K-12","termname":"Winter 2025-2026","teststartdate":"2026-01-28","testritscore":239,"testpercentile":91,"wintertowinterconditionalgrowthpercentile":43,"wintertowinterobservedgrowth":6,"wintertowinterprojectedgrowth":7,"typicalwintertowintergrowth":2,"normsreferencedata":2025,"growthmeasureyn":"true","goal1name":"Operations and Algebraic Thinking","goal1ritscore":241}]}'const response = await fetch(`${base}/alpha/analytics/v1/source-imports/timeback-map`, { method: "POST", headers: { Authorization: `Bearer ${token}`, "Idempotency-Key": "demo-import-001", "Content-Type": "application/json" }, body: JSON.stringify({ sourceBatchRef: "demo", rows: [] }) });
if (!response.ok) throw await response.json();
const body = await response.json();{
"import_id": "import_01J0MAPRESULTS",
"import_kind": "timeback-map",
"adapter_name": "timeback-map",
"source_system": "reporting",
"source_table": "hp_map_results",
"status": "materialized",
"submitted_row_count": 12,
"accepted_row_count": 12,
"materialized_row_count": 12,
"rejected_row_count": 0,
"problem_counts": {},
"completed_at": "2026-06-12T17:08:00Z"
}GET
/alpha/analytics/v1/source-imports
Inspect source-import status, materialized row counts, and typed problem counts. This is the audit trail for migration and backfill.
| Name | Type | Required | Description |
|---|---|---|---|
importKind | import_kind enum | Optional | Adapter/import kind, such as timeback-xp-time-accuracy or timeback-map. |
status | import_status enum | Optional | received, running, materialized, rejected, or another governed import status. |
modifiedSince | TIMESTAMPTZ | Optional | Poll for import status changes. |
limit | INTEGER | Optional | Page size. Default 100; maximum 1000. |
cursor | TEXT | Optional | Opaque next-page cursor. |
| Field | Type | Nullability | Meaning | Source |
|---|---|---|---|---|
import_id | TEXT | required | Stable id for this source import request. Generated by platform; unique per tenant. | dictionary |
import_kind | TEXT enum | required | Which source/replay contract this batch follows. Allowed values: import_kind enum. | dictionary |
status | TEXT enum | required | Processing state of the source import. Allowed values: import_status enum. | dictionary |
source_batch_ref | TEXT | nullable | Operator/source identifier for the imported file, replay, or reconciliation run. Opaque reference; no PII or raw row contents. | dictionary |
submitted_row_count | INTEGER | required | Number of source-shaped rows submitted in the batch. Nonnegative. | dictionary |
accepted_row_count | INTEGER | required | Rows accepted by request validation and adapter mapping. Nonnegative and not greater than submitted_row_count. | dictionary |
materialized_row_count | INTEGER | required | Rows that produced readable Analytics facts. Nonnegative; successful nonempty imports must produce readable rows unless status explains otherwise. | dictionary |
rejected_row_count | INTEGER | required | Rows rejected by validation or adapter mapping. Nonnegative; submitted = accepted + rejected for completed imports. | dictionary |
problem_counts | JSONB | required | Counts of typed Problem codes produced by the import. Keys must be stable analytics:* codes; values nonnegative integers. | dictionary |
modified_at | TIMESTAMPTZ | required | Last time the Analytics row changed for polling and modifiedSince queries. UTC timestamp; list endpoints support modifiedSince against this field. | dictionary |
curl -sS "$ANALYTICS_BASE_URL/alpha/analytics/v1/source-imports?importKind=timeback-map&modifiedSince=2026-06-10T00:00:00Z" \
-H "Authorization: Bearer $ANALYTICS_TOKEN"const response = await fetch(`${base}/alpha/analytics/v1/source-imports`, { headers: { Authorization: `Bearer ${token}` } });
if (!response.ok) throw await response.json();
const body = await response.json();{
"object": "list",
"url": "/alpha/analytics/v1/source-imports",
"data": [
{
"import_id": "imp_01HT8ANALYTICS",
"import_kind": "timeback-xp-time-accuracy",
"status": "materialized",
"source_batch_ref": "migration-2026-06-10-reporting-processed-facts-001",
"submitted_row_count": 5000,
"accepted_row_count": 4970,
"materialized_row_count": 4970,
"rejected_row_count": 30,
"problem_counts": {
"analytics:adapter_rejected": 30
},
"modified_at": "2026-06-10T00:56:12Z"
}
],
"hasMore": false,
"nextCursor": null,
"links": {
"self": "/alpha/analytics/v1/source-imports"
}
}Objects
alpha.analytics_event_time_factStores signed active, inactive, and waste second contributions for the DERIVED Events axis, so reports can audit time-on-task without classifying raw Caliper events themselves.
Grain: One source Event contribution per fact_kind, policy_ref, and calculation_version.
API: GET /alpha/analytics/v1/event-time-facts
aitd-000-extend-only-storage aitd-002-derived-events-complement aitd-003-close-time-materialization aitd-005-time-facts-and-windows
alpha.analytics_time_windowReport-ready active, inactive, and waste time totals for the DERIVED Events axis. These complement the ingested Time Commitment tile and support audit/Waste views.
Grain: student_id x subject_id nullable x window_kind x window_start x window_end x policy_ref.
API: GET /alpha/analytics/v1/time-windows
aitd-005-time-facts-and-windows aitd-002-derived-events-complement aitd-003-close-time-materialization aitd-011-policy-and-enum-normalization
alpha.analytics_school_day_minutesMinutes per enrolled school day for the Time Commitment tile. Numerator is ingested from reporting.processed_facts.active_seconds; denominator is alpha.school_calendar intersected with enrollment/subject assignment, with MAP-day exclusion.
Grain: student_id x school_id x subject_id nullable x window_start x window_end x school_day_policy_ref.
API: GET /alpha/analytics/v1/school-day-minutes
aitd-006-school-day-minutes aitd-001-report-source-ingestion aitd-004-provenance-no-literals aitd-005-time-facts-and-windows
alpha.analytics_xp_rollupReport-ready XP total plus goal progress fields. The goal fields use the same materialized school-day denominator as time commitment.
Grain: student_id x subject_id nullable x window_kind x window_start x window_end x policy_ref.
API: GET /alpha/analytics/v1/xp-rollups
aitd-007-xp-rollups aitd-001-report-source-ingestion aitd-004-provenance-no-literals aitd-003-close-time-materialization
alpha.analytics_accuracyReport-ready Accuracy panel facts: correct questions, total questions, incorrect questions, and percent correct without client-side processed_facts math.
Grain: student_id x subject_id nullable x window_kind x window_start x window_end x policy_ref.
API: GET /alpha/analytics/v1/accuracy-rollups
aitd-001-report-source-ingestion aitd-004-provenance-no-literals aitd-011-policy-and-enum-normalization aitd-003-close-time-materialization
alpha.analytics_mastery_deltaGrade Levels Mastered facts for the Learning Report plus a typed change log of mastery state movements; Results remains the current mastery state of record.
Grain: One state transition per student_id, kc_id|grade_scope, state_dimension, effective_at, policy_ref, and calculation_version.
API: GET /alpha/analytics/v1/mastery-deltas
aitd-008-mastery-and-grade-levels aitd-001-report-source-ingestion aitd-004-provenance-no-literals aitd-003-close-time-materialization
alpha.analytics_map_growth_rollupReport-ready RIT, achievement percentile, growth percentile, Growth X, MAP window, sitting-count, retake, and on-track facts without client-side norms tables, sitting selection, or term parsing.
Grain: student_id x subject_id x canonical_term_id x growth_window x norms_set x policy_ref.
API: GET /alpha/analytics/v1/map-growth-rollups
aitd-009-map-growth-rollups aitd-001-report-source-ingestion aitd-004-provenance-no-literals aitd-003-close-time-materialization
alpha.analytics_norms_achievementReadable NWEA achievement-status norms resource for percentile-to-RIT and RIT-to-percentile translation. Apps may read/cache the surface table by table_version or call /norms/rit and /norms/percentile; they never maintain their own norms table.
Grain: norms_set x table_version x subject_id x role x grade_key x season.
API: GET /alpha/analytics/v1/norms, GET /alpha/analytics/v1/norms/table, GET /alpha/analytics/v1/norms/rit, GET /alpha/analytics/v1/norms/percentile
aitd-015-norms-r90-readable-resources aitd-016-scale-translation-apis aitd-009-map-growth-rollups aitd-011-policy-and-enum-normalization
alpha.analytics_r90_tableReadable RIT-to-R90 and grade-position reference for GOALS target conversion, Learning Report grade-position display, and screener starting-grade hints. Final PowerPath placement comes from bottom-up grade-level mastery tests, not this table. Actual course and grade-level progress comes from completion-rollups. Analytics serves an Alpha-compatible mirror; the PowerPath RIT-to-grade master source is owned by NWEAMAP.
Grain: table_version x table_subject_id x rit_score.
API: GET /alpha/analytics/v1/r90/table, GET /alpha/analytics/v1/r90
aitd-015-norms-r90-readable-resources aitd-016-scale-translation-apis aitd-017-r90-version-supersession aitd-009-map-growth-rollups
analytics.school_days_remainingForward instructional-day count and XP-to-time effort projection for GOALS target-date columns. Apps call this endpoint or follow this raw path instead of counting weekdays, excluding MAP days, or carrying XP-hour constants locally.
Grain: One GOALS forward-calendar answer per student_id x school_id x half-open [as_of, end_date) request x school_day_policy_ref x XP expected-minute policy.
API: GET /alpha/analytics/v1/school-days-remaining
aitd-018-goals-school-days-remaining aitd-006-school-day-minutes aitd-007-xp-rollups aitd-016-scale-translation-apis
analytics.grade_level_statusGOALS age-grade status without local comparison logic: exactly two named comparisons, working vs age grade and mastered vs age grade.
Grain: One student_id x subject_id x as_of_date answer assembled from People and Orgs age grade and Results grade positions.
API: GET /alpha/analytics/v1/grade-level-status
aitd-102-axis-read-shape aitd-008-mastery-and-grade-levels aitd-011-policy-and-enum-normalization aitd-112-axis-list-endpoints
alpha.analytics_completion_rollupProgress evidence for Results and Analytics audits without MAP/RIT/R90 inference, client-side Curriculum tree walking, or Results-row counting.
Grain: student_id x completion_scope x scope_id x window_start x window_end x policy_ref.
API: GET /alpha/analytics/v1/completion-rollups
aitd-010-completion-rollups aitd-001-report-source-ingestion aitd-004-provenance-no-literals aitd-003-close-time-materialization
alpha.analytics_source_importProvenance spine for every ingested report-grade fact: adapter, source system/table, idempotency key, source-row natural-key/hash set, materialized counts, and per-row Problem summaries.
Grain: One named-adapter ingestion run from one report-source producer.
API: POST /alpha/analytics/v1/source-imports/{adapter} and GET /alpha/analytics/v1/source-imports
aitd-001-report-source-ingestion aitd-004-provenance-no-literals aitd-101-axis-write-granularity aitd-105-axis-idempotency
Grounding
The page examples stay at the approved contract level. These local evidence sidecars explain why the architecture requires server-side normalization and forbids client-side rollups.
| subject | n | active_seconds | inactive_seconds | waste_seconds | xp_earned |
|---|---|---|---|---|---|
| Writing | 4960405 | 78952263.87 | 7.08 | 0 | 1221796.13 |
| Math | 4007104 | 363185643.77 | 3812377.12 | 452971.58 | 4385760.04 |
| Language | 2211100 | 158180469.14 | 618341.92 | 311330.7 | 4907040.48 |
| FastMath | 2007884 | 70248577.86 | 480024.9 | 38318762.1 | 1063480.88 |
| Reading | 1789550 | 179081105.5 | 559883.94 | 124753.45 | 2950557.92 |
| type | action | n | deleted_n |
|---|---|---|---|
| TimeSpentEvent | SpentTime | 13098088 | 0 |
| ActivityEvent | Completed | 4165013 | 0 |
| Event | Created | 34481 | 0 |
| ToolUseEvent | Used | 3672 | 0 |
| AnnotationEvent | Tagged | 1583 | 0 |