Corrections API - Launch Grading and Retrieve Results

The Corrections API lets you trigger AI-powered grading for an exam and retrieve the results. Launching a correction is a single API call that enqueues all matching copies, Examino processes them asynchronously. You then poll GET /corrections to track progress and collect scores and feedback when they’re ready.

Launch corrections

Enqueues AI grading for copies in an exam. The response is immediate and does not wait for any copy to be processed. You can submit an entire class of 1300 copies in a single request. Required scope: corrections:write

The rubric must be validated in the web app before you launch (questionsValidated: true on the exam object). A launch attempted before validation is rejected.

string

required

A unique key you generate to deduplicate launch requests. Between 8 and 128 characters. If you retry with the same key, Examino returns the original result without re-launching or charging credits. See the Idempotency guide for recommendations.

string

default:"all"

Which copies to include:

all, every copy in the exam.
unreviewed, only copies whose correction has not yet been validated by an instructor. Use this to re-grade without overwriting work your team has already signed off on.

boolean

default:false

When relaunching after a rubric change, set to true to keep any manually-edited corrections as-is instead of recalculating them from scratch.

Request

curl -X POST https://app.examino.ai/api/v1/exams/aa11bb22-cc33-44dd-88ee-ff0011223344/corrections \
  -H "Authorization: Bearer $EXAMINO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "idempotencyKey": "sis-partiel-s1-2026-09-17-001",
    "scope": "all",
    "preserveEdits": false
  }'

Response 202

{
  "launchId": "c0ffee00-1111-4222-8333-444455556666",
  "launched": true,
  "alreadyRegistered": false,
  "targetCopiesCount": 1300
}

A 200 OK (instead of 202) indicates that the same idempotencyKey was already used. No new launch was created and no credits were reserved. The launch and every resulting credit consumption or refund are attributed to the API key used for this request, not to the user who created it.

Response fields

string

UUID identifying this correction launch.

boolean

true when the request was accepted and copies will be processed.

boolean

true when the provided idempotencyKey was already used for a previous launch. No duplication occurred and no credits were reserved for this call.

integer

Number of copies included in this launch.

Business refusal errors

When the launch cannot proceed, the API returns a structured error envelope:

Error envelope

{
  "error": {
    "code": "unprocessable",
    "message": "Le lancement a été refusé.",
    "details": { "reason": "INSUFFICIENT_CREDITS" }
  },
  "requestId": "…"
}

Check error.details.reason to determine the cause:

`reason`	Status	Meaning
`INSUFFICIENT_CREDITS`	422	Your credit balance is too low for the target volume. Top up in the Credits section.
`GRADING_SCALE_LOCKED`	422	The rubric is not in a state that allows a launch. Check validation status in the web app.
`NO_COPIES`	422	No copies match the requested `scope`.
`SUBJECT_PAGE_LIMIT_EXCEEDED`	422	The exam subject exceeds the maximum page limit for your plan.
`COPY_PAGE_LIMIT_EXCEEDED`	422	At least one copy exceeds the 100-page limit.
`LAUNCH_ALREADY_PENDING`	409	A correction launch is already in progress for this exam. Wait for it to complete before submitting another.

Get correction results

Returns one row per copy with its active correction result. Use this endpoint to track progress after a launch and to export grades when processing is complete. Required scope: corrections:read Results are sorted by index then by creation date, matching the order of GET /copies.

Always filter on status === "success" before aggregating. A correction row is attached to a copy at launch time, before any result is ready, rows in processing or error status have null scores. Including them in grade averages would count as zeros and produce incorrect results.

Request

curl "https://app.examino.ai/api/v1/exams/aa11bb22-cc33-44dd-88ee-ff0011223344/corrections" \
  -H "Authorization: Bearer $EXAMINO_API_KEY"

Response 200

{
  "items": [
    {
      "copyId": "11112222-3333-4444-8555-666677778888",
      "studentName": "Camille Dupont",
      "idProvidedByUser": "ETU-2026-0417",
      "index": 1,
      "reviewedAt": "2026-09-16T08:12:44.001Z",
      "correctionId": "99990000-aaaa-4bbb-8ccc-ddddeeeeffff",
      "status": "success",
      "noteTotal": 14.5,
      "noteMax": 20,
      "comment": "Une copie solide sur la partie stratégique…",
      "strongPoints": "Maîtrise du vocabulaire, exemples pertinents.",
      "gaps": "Le calcul du ROI reste approximatif.",
      "updatedAt": "2026-09-16T08:12:44.001Z"
    },
    {
      "copyId": "22223333-4444-5555-8666-777788889999",
      "studentName": "Alex Martin",
      "idProvidedByUser": "ETU-2026-0418",
      "index": 2,
      "reviewedAt": null,
      "correctionId": "88887777-6666-4555-8444-333322221111",
      "status": "processing",
      "noteTotal": null,
      "noteMax": null,
      "comment": null,
      "strongPoints": null,
      "gaps": null,
      "updatedAt": "2026-09-17T09:01:02.512Z"
    }
  ],
  "total": 2
}

Response fields

string

UUID of the copy.

string | null

Student name as provided at copy creation.

string | null

Your own student identifier, returned as-is. Use this to join results back to your SIS.

integer | null

Copy position within the exam, used for stable ordering.

string | null

ISO 8601 timestamp of when an instructor validated this correction. null means it has not yet been reviewed.

string | null

UUID of the active correction for this copy. null if the copy has never been put into correction.

string | null

Current status of the correction:

pending, queued, not yet started
processing, currently being graded
success, grading complete, results available
error, grading failed for this copy
retry, a transient failure occurred; Examino will retry automatically
null, this copy has never been put into correction

number | null

Score earned by the student. null until grading completes, and always null in competency grading mode.

number | null

Maximum possible score for this exam. null until grading completes, and always null in competency grading mode.

string | null

AI-generated overall feedback on the copy. null until grading completes.

string | null

AI-generated summary of what the student did well. null until grading completes.

string | null

AI-generated summary of areas for improvement. null until grading completes.

string

ISO 8601 timestamp of the last update to this correction row.

Polling for completion

Recommended polling strategy

Poll GET /exams/{examId}/corrections every 15–30 seconds after launching. The batch is fully complete when no item in the response has a status of pending, processing, or retry.

while any(item.status in ["pending", "processing", "retry"]):
    wait 15–30 seconds
    fetch GET /exams/{examId}/corrections

Once complete, filter on status === "success" to collect results. Any items left in error failed permanently.

Handling error copies

A copy with status: "error" means grading failed for that specific copy. Successfully graded copies are not re-billed if you relaunch.To retry failed copies:

Investigate the cause in the web app (e.g. illegible scan, corrupt file).
Replace or re-upload the copy file if necessary.
Launch again with a new idempotencyKey.

Copies that already have status: "success" will not be recalculated or re-charged.

Teams & Credits

Exams

Corrections API - Launch Grading and Retrieve Results

Launch corrections

Response fields

Business refusal errors

Get correction results

Response fields

Polling for completion

​Launch corrections

​Response fields

​Business refusal errors

​Get correction results

​Response fields

​Polling for completion

Launch corrections

Response fields

Business refusal errors

Get correction results

Response fields

Polling for completion