Results and reports

Retrieve a result

GET /v1/submissions/{id}/result returns the marks and feedback for every question. It is available once the submission is graded; before that you get 409 result_not_available.

{
  "object": "result",
  "livemode": true,
  "submission_id": "sub_7Hk2Pz9QaN",
  "paper_id": "pap_3fT9qLx2Wd",
  "status": "final",
  "student": { "external_id": "STU-0042", "name": "Ayesha K." },
  "score": { "awarded": 68, "available": 90, "percentage": 75.6 },
  "no_readable_answers": false,
  "graded_at": "2026-10-06T09:21:40Z",
  "released_at": "2026-10-06T09:21:40Z",
  "questions": [
    {
      "question_id": "q_4Ws9Tz1Bx6",
      "number": "3",
      "section": "Section A",
      "type": "written",
      "marks_available": 6,
      "marks_awarded": 5,
      "counted": true,
      "is_correct": false,
      "adjusted": false,
      "adjusted_by": null,
      "adjusted_at": null,
      "feedback": "Correct effect on current, but the power calculation is missing its unit.",
      "strengths": ["Links resistance to current correctly"],
      "improvements": ["Always give the unit with a final answer"],
      "explanation": null,
      "answer_text": "(a) Current goes down as resistance goes up.\n\n(b)(i) $P = IV = 6 \\times 0.5 = 3$",
      "selected_option": null,
      "parts": [
        {
          "key": "a",
          "label": "a",
          "marks_available": 2,
          "marks_awarded": 2,
          "is_correct": true,
          "adjusted": false,
          "feedback": "Both marking points made.",
          "explanation": null,
          "answer_text": "Current goes down as resistance goes up."
        },
        {
          "key": "b_i",
          "label": "b (i)",
          "marks_available": 4,
          "marks_awarded": 3,
          "is_correct": false,
          "adjusted": false,
          "feedback": "Correct method and value; the unit is missing.",
          "explanation": null,
          "answer_text": "$P = IV = 6 \\times 0.5 = 3$"
        }
      ]
    }
  ]
}

Field	Description
status	provisional while the submission is graded; final once it is released.
score, no_readable_answers	As on the Submission.
questions[].question_id	The question’s id from GET /v1/papers/{id}/questions, where you’ll find its text and answer key.
questions[].marks_awarded	Can be a decimal, such as 1.5.
questions[].counted	false when the paper’s choice rules leave this question out of the score. Its mark is still shown, but not added to score.
questions[].is_correct	true when full marks were awarded.
questions[].adjusted, adjusted_by, adjusted_at	Whether a reviewer changed our mark or feedback, the reviewer named on their review link, and when.
questions[].feedback	Our feedback on the answer, in our text format. One sentence when the paper’s grading.feedback is brief; null when it is none. At every level, a question that got 0 because it had no answer, or because the script had no readable answers, says so in full.
questions[].strengths, questions[].improvements	Short points on what went well and what to work on. Empty when they don’t apply, as for multiple choice, and when grading.feedback is none or brief.
questions[].explanation	When grading.feedback is detailed: the idea behind the question, for a question the student lost marks on, in our text format. Otherwise null.
questions[].answer_text	What we read from the script for this question, or null if the student didn’t answer it.
questions[].selected_option	For multiple choice, the label of the option the student chose, or null.
questions[].parts	One entry per part, with key, label, marks_available, marks_awarded, is_correct, adjusted, feedback, explanation and answer_text. A part’s answer_text is null when we couldn’t split the answer by part; the question’s answer_text always has the whole answer. The question’s marks combine its parts’ marks, capped at the question’s total. Empty when the question has no parts, and when it was marked as a whole and its mark can’t be split by part.

Download the report

GET /v1/submissions/{id}/report returns a link to a PDF report of the marked script, ready to give to the student. The report is a document we generate, not an annotated copy of the scan. It opens with a cover showing the student, the paper and the total score, and carries the AIDE AI name. It is available once the submission is released; before that you get 409 report_not_available.

Parameter	Description
sections	The sections to include after the cover, separated by commas: marks (a table of marks by question), summary (strengths and areas to improve) and feedback (each question with the answer we read and our feedback). Default: all three. A section the paper’s grading.feedback leaves empty is skipped: none gives marks only, and brief has no summary.

Response 200:

{
  "object": "report",
  "submission_id": "sub_7Hk2Pz9QaN",
  "status": "ready",
  "sections": ["marks", "summary", "feedback"],
  "url": "https://...",
  "expires_at": "2026-10-06T09:45:00Z"
}

• The url is a pre-signed link that works for 15 minutes. Download the PDF and store it yourself; don’t store the link.
• We render a report the first time it is requested for a given set of sections. Until it is ready you get 202 Accepted with a Retry-After header and the same body with "status": "rendering", url null and expires_at null. Ask again after Retry-After seconds.
• Later requests return the same file, unless the paper’s title or the student’s name has changed since; then we render it again.
• sections in the response lists the sections the report holds, after any the paper’s grading.feedback leaves empty are skipped.