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

# Grade with AI

> Score a submission against the assignment's rubric. Async.

## Path parameters

<ParamField path="id" type="string" required />

## Body

<ParamField body="rubric" type="Rubric">
  Override the assignment's rubric for this submission only.
</ParamField>

<ParamField body="model" type="string">Pin a specific model.</ParamField>

## Behaviour

Triggers async grading. The submission's `ai_status` flips
`pending` → `ready` (or `error`). Subscribe to the
`submission.graded` webhook or poll.

## Examples

<CodeGroup>
  ```ts TypeScript theme={null}
  await hk.submissions.gradeWithAi("sub_123");

  const graded = await hk.poll(
    () => hk.submissions.retrieve("sub_123"),
    { until: s => s.ai_status === "ready" },
  );
  ```

  ```php PHP theme={null}
  $hk->submissions->gradeWithAi('sub_123');

  $graded = $hk->poll(
      fn () => $hk->submissions->retrieve('sub_123'),
      ['until' => fn ($s) => $s->ai_status === 'ready'],
  );
  ```
</CodeGroup>

## Related

* [`submissions.explainGrade(id)`](/api-reference/overview) — fill in
  the AI rationale for a manually-graded submission.

## Returns

The submission with `ai_status: "pending"`.