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

> Trigger scoring on one session or in bulk, and read the rubric breakdown and final score. Scores cannot be changed by hand.

# 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,
      "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>

***

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

<ParamField body="sessionIds" type="string[]" required>
  Up to 500 session ids. Duplicates are removed before processing.
</ParamField>

<Accordion title="Response">
  ```json theme={null}
  {
    "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'." }
    ]
  }
  ```
</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,
      "scoredAt": "2025-01-15T12:00:00Z",
      "reviewedAt": null,
      "reviewedById": null
    }
  }
  ```
</Accordion>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.