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.

sessionId

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,
    "percentileCategory": 72,
    "percentileGlobal": 68,
    "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'."
  }
}

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,
    "percentileCategory": 72,
    "percentileGlobal": 68,
    "scoredAt": "2025-01-15T12:00:00Z",
    "reviewedAt": null,
    "reviewedById": null
  }
}

Override Score (Admin Review)

PATCH /api/scoring/:sessionId

Applies admin score overrides and marks the session as reviewed. Use this when a human reviewer wants to adjust the automated scores.

adminScores

object

required

Admin-assigned scores by category (e.g. {"deliverable_quality": 25, "delegation": 8})

notes

string

Review notes

Response

{
  "score": {
    "id": "uuid",
    "sessionId": "uuid",
    "autoScores": { "..." },
    "adminScores": { "deliverable_quality": 25, "delegation": 8 },
    "finalScore": 65,
    "reviewedAt": "2025-01-16T09:00:00Z",
    "reviewedById": "uuid"
  }
}

​Scoring

​Trigger Scoring

​Get Score

​Override Score (Admin Review)

Scoring

Trigger Scoring

Get Score

Override Score (Admin Review)