Gradebook report

A course run's released results as an Excel sheet, CSV or printable PDF pack.

PriceFree
Typical time3 s to 45 s
Scopereports:read
Runs asA background job

Try it

Run gradebook report in the sandbox

No key and nothing to pay. The sandbox returns a realistic example in a couple of seconds; no AI runs and no data is kept.

Queued202 and a job id, straight away
ProcessingPoll, stream or wait for a webhook
SucceededResult and files on the job

Every AI request runs as a background job, so nothing times out.

Builds the same file as the Gradebook's Export button: one row per learner with each item's released result, or a progress report per learner as a PDF. Only released results are included. Free. Download the file from GET /jobs/{job_id}/files/gradebook.xlsx (or .csv / .pdf).

Requires reports:read. Free. Send a unique Idempotency-Key; reuse it with the identical body when retrying. Returns 202 with a job: poll GET /jobs/{job_id}, stream GET /jobs/{job_id}/events, or use a signed webhook.

Gradebook report

POST/v1/reports/gradebook

Scope reports:read

Headers

Gradebook report: headers
Field	Details
`Idempotency-Key`	stringRequiredA unique key per new operation; reuse it with the identical body when retrying.
`EduMark-Version`	enumAPI version. Defaults to the latest.One of `2026-10-21`

Request body

Gradebook report: request body
Field	Details
`run_id`	stringRequiredThe course run (GET /v1/course-runs).Up to 200 charactersPattern `^[A-Za-z0-9][A-Za-z0-9._:-]{0,199}$`
`format`	enumxlsx or csv: one row per learner. pdf: a progress report per learner.One of `xlsx`, `csv`, `pdf`Default `"xlsx"`
`learner_ids`	array of string, optionalOnly these learners.1 to 5,000 items
`include_ids`	booleanAdd a learner ID column.Default `true`
`include_status`	booleanAdd each learner's status (on track, needs attention…).Default `true`
`include_feedback`	booleanPDF only: include released feedback.Default `false`

Responses

Status	Meaning
202	Successful Response
400	Request rejected. Inspect error.code and request_id; failed work is not billed.
401	Request rejected. Inspect error.code and request_id; failed work is not billed.
402	Request rejected. Inspect error.code and request_id; failed work is not billed.
403	Request rejected. Inspect error.code and request_id; failed work is not billed.
404	Request rejected. Inspect error.code and request_id; failed work is not billed.
409	Request rejected. Inspect error.code and request_id; failed work is not billed.
410	Request rejected. Inspect error.code and request_id; failed work is not billed.
413	Request rejected. Inspect error.code and request_id; failed work is not billed.
415	Request rejected. Inspect error.code and request_id; failed work is not billed.
422	Validation Error
429	Request rejected. Inspect error.code and request_id; failed work is not billed.
503	Request rejected. Inspect error.code and request_id; failed work is not billed.

Request

curl -X POST 'https://api.edumark.ai/v1/reports/gradebook' \
  -H "Authorization: Bearer $EDUMARK_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "run_id": "delivery_7c1f02",
  "format": "xlsx"
}'

# Then poll until the job finishes (wait poll_after_seconds between calls)
curl 'https://api.edumark.ai/v1/jobs/job_01JB7Q8M4X2V9R' \
  -H "Authorization: Bearer $EDUMARK_API_KEY"

Queued202 and a job id, straight away
ProcessingPoll, stream or wait for a webhook
SucceededResult and files on the job

Every AI request runs as a background job, so nothing times out.

Response 202JSON

{
  "id": "job_0123456789abcdef0123456789abcdef01234567",
  "product": "reports_gradebook",
  "status": "queued",
  "poll_after_seconds": 2,
  "credits": 0,
  "result_available": false
}

Finished job: resultJSON

{
  "report": "gradebook",
  "run_id": "delivery_7c1f02",
  "title": "Biology, autumn 2026",
  "course_title": "GCSE Biology: Cells and energy",
  "format": "xlsx",
  "learners": 3,
  "items": 2,
  "released_results_only": true,
  "file": {
    "name": "gradebook.xlsx",
    "mime_type": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
    "size_bytes": 18734
  },
  "note": null
}