Results & Progress API

Bring your students' PrepareBuddy scores into your own system — a CRM, a student information system, a spreadsheet, a BI dashboard — on any schedule. It is the same organization API key and base URL as the provisioning endpoints, and it only reads: a read-only key is all it needs. New to APIs? Start with the API Quick Start; for a ready-made spreadsheet, see Recipe: Scores into Google Sheets.

Base URL: https://www.preparebuddy.com/api/v1/ (or your own PrepareBuddy address)

X-API-Key: <your-key>

Want results pushed as they happen? See Webhooks — the payload is the same result object.

Which results you get

• Your students only: people who are members of your organization. Language-test practice they do is included; work assigned by another organization is not. (Details: Scope.)
• Final results only, at the moment the student sees them:
• a language test when it is finished — or, if your teachers review results first, when it is released;
• a quiz when it is submitted;
• an assessment when its feedback is released to the student.
• Re-marks: if a result is re-scored later (for example a speaking answer finishes AI grading, or a teacher releases revised feedback), the same result appears again with the new score. Always upsert by id.

GET /results/

curl -s "https://www.preparebuddy.com/api/v1/results/?limit=100" -H "X-API-Key: <key>"

Query parameters

Response

{
  "status": "ok",
  "count": 1,
  "has_more": false,
  "next_cursor": "WyIyMDI2LTA5LTI3VDEwOjE1OjAzKzAwOjAwIiwgMCwgNDEyXQ",
  "results": [
    {
      "id": "test:3f8b2c1e-6a0d-4c7e-9b1a-2d4e5f6a7b8c",
      "kind": "test",
      "student": {"user_id": 812, "email": "asha.rao@uni.example", "first_name": "Asha", "last_name": "Rao"},
      "item": {"id": 57, "title": "IELTS Academic Mock 3", "type": "ielts", "type_label": "IELTS"},
      "attempt": "practice",
      "section_practiced": null,
      "started_at": "2026-09-27T08:02:11+00:00",
      "completed_at": "2026-09-27T10:15:03+00:00",
      "released_at": null,
      "score": 7.5,
      "max_score": 9,
      "percentage": 83.3,
      "score_label": "IELTS band 7.5 / 9",
      "sections": {"listening": 8.0, "reading": 7.5, "writing": 6.5, "speaking": 7.0},
      "result_url": "https://www.preparebuddy.com/language-tests/session/3f8b2c1e-…/result/"
    }
  ]
}

Nightly sync, the whole recipe

1. First run: call /results/ without a cursor; keep calling with cursor=<next_cursor> while has_more is true. Store the last next_cursor.
2. Every night: call /results/?cursor=<stored cursor> the same way, and store the new next_cursor.
3. Upsert each result by id.

next_cursor always points after the last result you received, so you never miss or double-count one, even if your job fails half-way — just run it again from the last cursor you stored.

GET /progress/daily/

A ready-made trend: per student, per day, per test type.

curl -s "https://www.preparebuddy.com/api/v1/progress/daily/?email=asha.rao@uni.example&from=2026-09-01&to=2026-09-30&tz=Asia/Kolkata" \
     -H "X-API-Key: <key>"

{
  "status": "ok", "from": "2026-09-01", "to": "2026-09-30", "timezone": "Asia/Kolkata", "count": 2,
  "days": [
    {"student": {"user_id": 812, "email": "asha.rao@uni.example", "first_name": "Asha", "last_name": "Rao"},
     "date": "2026-09-26", "kind": "test", "type": "ielts", "type_label": "IELTS",
     "attempts": 2, "average_percentage": 80.6, "best_percentage": 83.3,
     "average_score": 7.25, "best_score": 7.5, "max_score": 9},
    {"student": {"user_id": 812, "email": "asha.rao@uni.example", "first_name": "Asha", "last_name": "Rao"},
     "date": "2026-09-27", "kind": "quiz", "type": "quiz", "type_label": "Quiz",
     "attempts": 1, "average_percentage": 75.0, "best_percentage": 75.0,
     "average_score": 75, "best_score": 75, "max_score": 100}
  ]
}

average_score, best_score and max_score are on the test's own scale and are null when that day mixes different scales (for example a full SAT and a one-section SAT practice); average_percentage is always given. Days with no finished work are not listed.

Scope

A student who belongs to two organizations is therefore reported to each only for their own and self-chosen practice work, never for the other organization's assignments.

Errors