Course runs

Create and manage runs of your courses for cohorts or chosen people, on dates or at their own pace.

Scopescourse_runs:readcourse_runs:write

Data requests act inside the key’s centre as the person who created the key: each needs the scope and that person’s current EduMark permission. See auth and pagination.

List course runs

GET/v1/course-runs

Runs the key's creator can see, newest first. A page can hold fewer than limit runs.

Scope course_runs:read

Parameters

List course runs: parameters
Field	Details
`limit`	integerItems per page, 1 to 100.1 to 100Default `25`
`cursor`	string, optionalThe `next_cursor` from the previous page.Up to 512 characters
`updated_since`	string, optional
`course_id`	string, optionalUp to 200 characters
`status`	enum, optionalOne of `draft`, `active`, `paused`, `ended`, `archived`

Headers

List course runs: headers
Field	Details
`EduMark-Version`	enumAPI version. Defaults to the latest.One of `2026-10-21`

Responses

Status	Meaning
200	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.
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.

Create a course run

POST/v1/course-runs

Creates a run of a published course for a cohort, chosen people or everyone, on dates or at their own pace. With start: true the run also starts: the answer is 202 and start.status shows progress on GET /course-runs/{id}.

Scope course_runs:write

Headers

Create a course run: headers
Field	Details
`Idempotency-Key`	stringRequiredA unique key per new run.
`EduMark-Version`	enumAPI version. Defaults to the latest.One of `2026-10-21`

Request body

Create a course run: request body
Field	Details
`course_id`	stringRequiredA published course.Up to 200 characters
`name`	stringLeave empty for a suggested name.Up to 300 charactersDefault `""`
`opens_at`	string (date-time), optionalWhen learners can start. Empty opens it when started.
`finish_by`	string (date-time), optionalTarget finish date. Empty for own pace.
`closes_at`	string (date-time), optionalWhen access closes. Empty keeps it open.
`timezone`	string, optionalIANA zone. Defaults to your team's zone.Up to 64 characters
`audience`	Audience
`mode`audience.mode	enumnone, everyone in your team, or the selected cohorts and people.One of `none`, `everyone`, `selected`Default `"none"`
`cohort_ids`audience.cohort_ids	array of stringUp to 100 items
`learner_ids`audience.learner_ids	array of stringUp to 500 items
`excluded_learner_ids`audience.excluded_learner_ids	array of stringUp to 500 items
`certificate`	booleanDefault `true`
`start`	booleanStart the run straight away (runs in the background).Default `false`

Responses

Status	Meaning
201	Successful Response
202	Created and starting in the background
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.
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/course-runs' \
  -H "Authorization: Bearer $EDUMARK_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "audience": {
    "cohort_ids": [
      "cohort_6b1f2c3d4e5f"
    ],
    "mode": "selected"
  },
  "course_id": "course_1a2b3c4d5e6f",
  "name": "Biology, autumn 2026",
  "opens_at": "2026-09-08T08:00:00Z",
  "start": true
}'

Response 201JSON

{
  "audience": {
    "cohort_ids": [
      "cohort_6b1f2c3d4e5f"
    ],
    "excluded_learner_ids": [],
    "learner_ids": [],
    "mode": "selected"
  },
  "certificate": true,
  "closes_at": "2026-12-18T17:00:00Z",
  "course_id": "course_1a2b3c4d5e6f",
  "course_title": "GCSE Biology: Cells and energy",
  "created_at": "2026-09-01T09:00:00Z",
  "finish_by": "2026-12-11T17:00:00Z",
  "id": "cdel_2f9c1a7b8e",
  "learner_count": 28,
  "name": "Biology, autumn 2026",
  "opens_at": "2026-09-08T08:00:00Z",
  "pace": "dated",
  "phase": "running",
  "progress": {
    "certificates": 2,
    "finished": 2,
    "learners": 28,
    "needs_attention": 2,
    "not_started": 3,
    "on_track": 19,
    "waiting_on_marking": 2
  },
  "status": "active",
  "timezone": "Europe/London",
  "updated_at": "2026-09-08T08:00:03Z"
}

Get a course run

GET/v1/course-runs/{run_id}

Scope course_runs:read

Parameters

Get a course run: parameters
Field	Details
`run_id`	stringRequired

Headers

Get a course run: headers
Field	Details
`EduMark-Version`	enumAPI version. Defaults to the latest.One of `2026-10-21`

Responses

Status	Meaning
200	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.
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 'https://api.edumark.ai/v1/course-runs/run_123' \
  -H "Authorization: Bearer $EDUMARK_API_KEY"

Response 200JSON

{
  "audience": {
    "cohort_ids": [
      "cohort_6b1f2c3d4e5f"
    ],
    "excluded_learner_ids": [],
    "learner_ids": [],
    "mode": "selected"
  },
  "certificate": true,
  "closes_at": "2026-12-18T17:00:00Z",
  "course_id": "course_1a2b3c4d5e6f",
  "course_title": "GCSE Biology: Cells and energy",
  "created_at": "2026-09-01T09:00:00Z",
  "finish_by": "2026-12-11T17:00:00Z",
  "id": "cdel_2f9c1a7b8e",
  "learner_count": 28,
  "name": "Biology, autumn 2026",
  "opens_at": "2026-09-08T08:00:00Z",
  "pace": "dated",
  "phase": "running",
  "progress": {
    "certificates": 2,
    "finished": 2,
    "learners": 28,
    "needs_attention": 2,
    "not_started": 3,
    "on_track": 19,
    "waiting_on_marking": 2
  },
  "status": "active",
  "timezone": "Europe/London",
  "updated_at": "2026-09-08T08:00:03Z"
}

Update a course run

PATCH/v1/course-runs/{run_id}

Changes the name, dates, time zone or certificate setting. Moving the dates of a running run answers 202 while every learner's access is updated.

Scope course_runs:write

Parameters

Update a course run: parameters
Field	Details
`run_id`	stringRequired

Headers

Update a course run: headers
Field	Details
`EduMark-Version`	enumAPI version. Defaults to the latest.One of `2026-10-21`

Request body

Update a course run: request body
Field	Details
`name`	string, optionalUp to 300 characters
`opens_at`	string (date-time), optional
`finish_by`	string (date-time), optional
`closes_at`	string (date-time), optional
`timezone`	string, optionalUp to 64 characters
`certificate`	boolean, optional

Responses

Status	Meaning
200	Successful Response
202	Dates are being applied to every learner in the background
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.
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 PATCH 'https://api.edumark.ai/v1/course-runs/run_123' \
  -H "Authorization: Bearer $EDUMARK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "finish_by": "2026-12-11T17:00:00Z"
}'

Response 200JSON

{
  "audience": {
    "cohort_ids": [
      "cohort_6b1f2c3d4e5f"
    ],
    "excluded_learner_ids": [],
    "learner_ids": [],
    "mode": "selected"
  },
  "certificate": true,
  "closes_at": "2026-12-18T17:00:00Z",
  "course_id": "course_1a2b3c4d5e6f",
  "course_title": "GCSE Biology: Cells and energy",
  "created_at": "2026-09-01T09:00:00Z",
  "finish_by": "2026-12-11T17:00:00Z",
  "id": "cdel_2f9c1a7b8e",
  "learner_count": 28,
  "name": "Biology, autumn 2026",
  "opens_at": "2026-09-08T08:00:00Z",
  "pace": "dated",
  "phase": "running",
  "progress": {
    "certificates": 2,
    "finished": 2,
    "learners": 28,
    "needs_attention": 2,
    "not_started": 3,
    "on_track": 19,
    "waiting_on_marking": 2
  },
  "status": "active",
  "timezone": "Europe/London",
  "updated_at": "2026-09-08T08:00:03Z"
}

Start a course run

POST/v1/course-runs/{run_id}/start

Gives everyone on the run access and sends their invitations (at the opening time if that is later). Answers 202; poll GET /course-runs/{id} until status is active.

Scope course_runs:write

Parameters

Start a course run: parameters
Field	Details
`run_id`	stringRequired

Headers

Start a course run: headers
Field	Details
`EduMark-Version`	enumAPI version. Defaults to the latest.One of `2026-10-21`

Responses

Status	Meaning
200	Successful Response
202	Starting in the background
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.
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/course-runs/run_123/start' \
  -H "Authorization: Bearer $EDUMARK_API_KEY"

Response 200JSON

{
  "audience": {
    "cohort_ids": [
      "cohort_6b1f2c3d4e5f"
    ],
    "excluded_learner_ids": [],
    "learner_ids": [],
    "mode": "selected"
  },
  "certificate": true,
  "closes_at": "2026-12-18T17:00:00Z",
  "course_id": "course_1a2b3c4d5e6f",
  "course_title": "GCSE Biology: Cells and energy",
  "created_at": "2026-09-01T09:00:00Z",
  "finish_by": "2026-12-11T17:00:00Z",
  "id": "cdel_2f9c1a7b8e",
  "learner_count": 28,
  "name": "Biology, autumn 2026",
  "opens_at": "2026-09-08T08:00:00Z",
  "pace": "dated",
  "phase": "running",
  "progress": {
    "certificates": 2,
    "finished": 2,
    "learners": 28,
    "needs_attention": 2,
    "not_started": 3,
    "on_track": 19,
    "waiting_on_marking": 2
  },
  "status": "active",
  "timezone": "Europe/London",
  "updated_at": "2026-09-08T08:00:03Z"
}