# Submissions & Grading

> Read submissions and attachments, grade or request resubmission, export results.

Canonical: https://grout.app/developer/documentation/exams/submissions/

## Status flow

`submitted` → `graded` | `resubmission_required` | `voided`. A student resubmitting creates a new version (`version` increments); previous versions stay readable.

## List and read

```bash
curl "$API/submissions?exam_id=ex_…&status=submitted" -H "Authorization: Bearer $KEY"
curl "$API/submissions?student_id=student143.4f9a2b1c@grout.user&since=2026-09-01T00:00:00Z" -H "Authorization: Bearer $KEY"
curl $API/submissions/sub_… -H "Authorization: Bearer $KEY"
```

`GET /submissions/{id}` returns the text, `attachments` and `feedback_attachments` as **signed URLs valid one hour**, `ai_usage_data`, `score_detail`, and a `proctoring` summary. Recording URLs are included only when the key holds `submissions:write`.

## Grade

```bash
curl -X POST $API/submissions/sub_…/grade -H "Authorization: Bearer $KEY" -H 'Content-Type: application/json' \
  -d '{ "score": 87, "feedback": "Good work", "graded_by": "faculty3.4f9a2b1c@grout.user" }'
```

- `score` must not exceed the exam's `max_score`.
- `score: -1` requests a **resubmission**; students and verified guardians are emailed.
- `graded_by` is optional; defaults to the exam owner.

Late submissions have the exam's `late_penalty_percentage` applied automatically; `score_detail.percentage` reflects the final value.

## Void

```bash
curl -X POST $API/submissions/sub_…/void -H "Authorization: Bearer $KEY" -H 'Content-Type: application/json' -d '{ "reason": "duplicate" }'
```

## Export

`GET /exams/{id}/export.csv` streams `email,student_id,status,score,max_score,percentage,is_late,submitted_at,graded_at`.

## Events

`exam.submitted` on every version; `exam.graded` on grade **and** on resubmission request (`resubmission_required: true`). Pair with [Gradebook Sync](/developer/documentation/guides/gradebook/).