Scoring

The scoring engine evaluates submitted sessions using an LLM-as-judge approach across multiple categories. Scores include automated ratings, percentile rankings, and suggested follow-up interview questions.

Trigger Scoring

POST /api/scoring

Runs the automated scoring pipeline on a submitted session. Can also be used to re-score an already-scored session.

string

required

The session to score

The session must be in submitted or scored status. Attempting to score a session in another status returns a 409 Conflict error.

curl -X POST https://app.trygradient.ai/api/scoring \
  -H "Authorization: Bearer gai_your_key" \
  -H "Content-Type: application/json" \
  -d '{"sessionId": "SESSION_ID"}'

const res = await fetch('https://app.trygradient.ai/api/scoring', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${apiKey}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ sessionId })
});
const { score } = await res.json();

Response

{
  "score": {
    "id": "uuid",
    "sessionId": "uuid",
    "autoScores": {
      "categories": {
        "deliverable_quality": { "score": 22, "maxPoints": 30, "subCriteria": {} },
        "delegation": { "score": 7, "maxPoints": 10, "subCriteria": {} },
        "description": { "score": 11, "maxPoints": 15, "subCriteria": {} },
        "discernment": { "score": 12, "maxPoints": 15, "subCriteria": {} },
        "diligence": { "score": 8, "maxPoints": 10, "subCriteria": {} }
      },
      "rawTotal": 60,
      "finalTotal": 60
    },
    "finalScore": 60,
    "summaryText": "The candidate demonstrated strong...",
    "feedbackText": "Your deliverable showed...",
    "followUpQuestions": [
      {
        "categoryId": "discernment",
        "question": "I noticed you accepted the AI's revenue figures without cross-checking. Walk me through your verification process.",
        "rationale": "The deliverable contained a revenue figure that didn't match the seeded earnings report.",
        "lookFor": "Strong: acknowledges the gap. Weak: doesn't recognize the error."
      }
    ],
    "percentileThisAssessment": 85,
    "scoredAt": "2025-01-15T12:00:00Z"
  }
}

Error - Wrong Status (409)

{
  "error": {
    "code": "conflict",
    "message": "Session is in 'in_progress' status and cannot be scored. Must be 'submitted' or 'scored'."
  }
}

Bulk Trigger Scoring

POST /api/scoring/bulk

Dispatches scoring for every listed session in one request instead of one request per session. Dispatch only: each item just starts scoring the same way Trigger Scoring above does; the resulting score is not returned here (poll Get Score below). This route is dispatch-and-collect: it always returns 200, even when some items fail, and each item carries its own outcome. The single-session route above still exists for the per-row action.

string[]

required

Up to 500 session ids. Duplicates are removed before processing.

Response

{
  "results": [
    { "id": "session-1", "ok": true },
    { "id": "session-2", "ok": false, "error": "Session is in 'in_progress' status and cannot be scored. Must be 'submitted' or 'scored'." }
  ]
}

Get Score

GET /api/scoring/:sessionId

Retrieves the score record for a session.

Response

{
  "score": {
    "id": "uuid",
    "sessionId": "uuid",
    "autoScores": { "..." },
    "adminScores": null,
    "finalScore": 78,
    "summaryText": "...",
    "feedbackText": "...",
    "percentileThisAssessment": 85,
    "scoredAt": "2025-01-15T12:00:00Z",
    "reviewedAt": null,
    "reviewedById": null
  }
}

Overview

Endpoints

Scoring API

Scoring

Trigger Scoring

Bulk Trigger Scoring

Get Score

​Scoring

​Trigger Scoring

​Bulk Trigger Scoring

​Get Score

Scoring

Trigger Scoring

Bulk Trigger Scoring

Get Score