> ## Documentation Index
> Fetch the complete documentation index at: https://trygradient.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Scoring

> Trigger automated scoring and review results

# 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.

<ParamField body="sessionId" type="string" required>
  The session to score
</ParamField>

<Info>The session must be in `submitted` or `scored` status. Attempting to score a session in another status returns a `409 Conflict` error.</Info>

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://app.trygradient.ai/api/scoring \
    -H "Authorization: Bearer gai_your_key" \
    -H "Content-Type: application/json" \
    -d '{"sessionId": "SESSION_ID"}'
  ```

  ```javascript Node.js theme={null}
  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();
  ```
</CodeGroup>

<Accordion title="Response">
  ```json theme={null}
  {
    "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"
    }
  }
  ```
</Accordion>

<Accordion title="Error - Wrong Status (409)">
  ```json theme={null}
  {
    "error": {
      "code": "conflict",
      "message": "Session is in 'in_progress' status and cannot be scored. Must be 'submitted' or 'scored'."
    }
  }
  ```
</Accordion>

***

## Get Score

```
GET /api/scoring/:sessionId
```

Retrieves the score record for a session.

<Accordion title="Response">
  ```json theme={null}
  {
    "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
    }
  }
  ```
</Accordion>

***

## 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.

<ParamField body="adminScores" type="object" required>
  Admin-assigned scores by category (e.g. `{"deliverable_quality": 25, "delegation": 8}`)
</ParamField>

<ParamField body="notes" type="string">
  Review notes
</ParamField>

<Accordion title="Response">
  ```json theme={null}
  {
    "score": {
      "id": "uuid",
      "sessionId": "uuid",
      "autoScores": { "..." },
      "adminScores": { "deliverable_quality": 25, "delegation": 8 },
      "finalScore": 65,
      "reviewedAt": "2025-01-16T09:00:00Z",
      "reviewedById": "uuid"
    }
  }
  ```
</Accordion>