# Quiz attempts · Management API

> Management API reference for quiz attempts: GET /sites/{id}/quiz-attempts, POST /sites/{id}/quiz-attempts/grant-retry.

> Markdown version of https://kanorio.com/en/developers/management-api/quiz_attempts. Append `.md` to any developer docs URL for this format. Index: https://kanorio.com/llms.txt · MCP: https://app.kanorio.com/api/mcp

Base URL: `https://app.kanorio.com/api/v1` · [Errors](https://kanorio.com/en/developers/basics/errors) · [Pagination](https://kanorio.com/en/developers/basics/pagination)

### List quiz attempts

`GET /sites/{id}/quiz-attempts`

- Stability: beta
- Permission: `customers:view`
- Rate limit: default (120/minute per token)
- MCP tool: `quiz_attempts_list`

List quiz attempts, newest first, filtered by deliverable, unit and/or contact. Each attempt carries the snapshot taken when it was submitted (mode, passing score, per-question results and the learner's answers), so editing questions later does not change it; perQuestion keys are question ids of the unit's quiz body. Attempts from before snapshots existed have null correct/total/passingPercent and perQuestion regraded against the current questions. Errors: FORBIDDEN, INVALID_CURSOR.

**Parameters**

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string | yes | Website id. Get it from sites.list or from sites.create. |
| `deliverableId` | query | string | no | Deliverable id. Get it from deliverables.list. |
| `unitId` | query | string | no | Quiz unit id. |
| `contactId` | query | string | no | — |
| `limit` | query | integer | no | Maximum number of items to return, 1–100. Defaults to 20. |
| `cursor` | query | string | no | Opaque cursor from the previous page's nextCursor. Omit for the first page. |

**Response** (200)

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `data` | object[] | yes | — |
| `data[].id` | string | yes | — |
| `data[].contactId` | string | yes | — |
| `data[].deliverableId` | string | yes | — |
| `data[].unitId` | string | yes | — |
| `data[].attemptNo` | integer | yes | 1-based per learner and unit. |
| `data[].mode` | "graded" \| "practice" | yes | — |
| `data[].score` | integer | yes | 0-100. |
| `data[].correct` | integer \| null | yes | — |
| `data[].total` | integer \| null | yes | — |
| `data[].passingPercent` | integer \| null | yes | Passing score at the time; null for practice attempts and attempts from before snapshots. |
| `data[].passed` | boolean | yes | Always true for practice attempts. |
| `data[].createdAt` | string | yes | ISO-8601 timestamp with timezone, e.g. 2026-10-05T12:34:56.789Z. |
| `data[].perQuestion` | object | yes | Question id → correct. |
| `data[].answers` | object | yes | Question id → chosen option ids, or the typed answer for short_text/numeric questions. |
| `hasMore` | boolean | yes | True when another page exists; pass nextCursor to fetch it. |
| `nextCursor` | string \| null | yes | Cursor for the next page, or null on the last page. |

**Errors**

| Code | Status | When |
| --- | --- | --- |
| `FORBIDDEN` | 403 | — |
| `INVALID_CURSOR` | 400 | — |

```bash
curl -X GET "https://app.kanorio.com/api/v1/sites/{id}/quiz-attempts?unitId=unit_quiz_01&contactId=contact_example01&limit=20" \
  -H "Authorization: Bearer $KANORIO_TOKEN"
```

```json
{
  "data": [
    {
      "id": "qa_01",
      "contactId": "contact_example01",
      "deliverableId": "dlv_example01",
      "unitId": "unit_quiz_01",
      "attemptNo": 2,
      "mode": "graded",
      "score": 100,
      "correct": 3,
      "total": 3,
      "passingPercent": 70,
      "passed": true,
      "createdAt": "2026-10-06T08:00:00.000Z",
      "perQuestion": {
        "q1": true,
        "q2": true,
        "q3": true
      },
      "answers": {
        "q1": [
          "b"
        ],
        "q2": [
          "a",
          "c"
        ],
        "q3": [
          "Taipei"
        ]
      }
    }
  ],
  "hasMore": false,
  "nextCursor": null
}
```

### Grant retry

`POST /sites/{id}/quiz-attempts/grant-retry`

- Stability: beta
- Permission: `customers:manage`
- Rate limit: default (120/minute per token)
- MCP tool: `quiz_attempts_grant_retry`

Give one learner one more attempt on one graded quiz (the unit's maxAttempts plus extra attempts granted so far). Only allowed when the quiz is graded with an attempt limit, the learner has used every attempt and has not passed; past attempts and statistics are kept. Returns the new allowance. Errors: FORBIDDEN, UNIT_NOT_FOUND, NOT_A_QUIZ, QUIZ_NOT_READY, CONTACT_NOT_FOUND, QUIZ_RETRY_NOT_APPLICABLE.

**Parameters**

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string | yes | Website id. Get it from sites.list or from sites.create. |

**Request body**

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `deliverableId` | string | yes | Deliverable id. Get it from deliverables.list. |
| `unitId` | string | yes | Quiz unit id of that deliverable. |
| `contactId` | string | yes | — |

**Response** (200)

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `contactId` | string | yes | — |
| `unitId` | string | yes | — |
| `attemptsUsed` | integer | yes | — |
| `extraAttempts` | integer | yes | Extra attempts granted so far, including this one. |
| `maxAttempts` | integer \| null | yes | Attempts allowed now (unit setting plus extra attempts). |
| `attemptsLeft` | integer \| null | yes | — |
| `canAttempt` | boolean | yes | — |

**Errors**

| Code | Status | When |
| --- | --- | --- |
| `FORBIDDEN` | 403 | — |
| `UNIT_NOT_FOUND` | 404 | — |
| `NOT_A_QUIZ` | 409 | — |
| `QUIZ_NOT_READY` | 409 | — |
| `CONTACT_NOT_FOUND` | 404 | — |
| `QUIZ_RETRY_NOT_APPLICABLE` | 422 | — |

```bash
curl -X POST "https://app.kanorio.com/api/v1/sites/{id}/quiz-attempts/grant-retry" \
  -H "Authorization: Bearer $KANORIO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"deliverableId":"dlv_example01","unitId":"unit_quiz_01","contactId":"contact_example01"}'
```

```json
{
  "contactId": "contact_example01",
  "unitId": "unit_quiz_01",
  "attemptsUsed": 3,
  "extraAttempts": 1,
  "maxAttempts": 4,
  "attemptsLeft": 1,
  "canAttempt": true
}
```
