Create action plans with the API

Action Plans read the results of an exam you already evaluated and say what to do next. One plan is for the teacher and covers the whole class. The other is for a single student. Each plan takes two API calls: one to start it, one to collect it. This guide is for developers. For a non-technical overview, see Teacher Action Plan features and Student Action Plan features.

Step	You call	You get back	Who reads it
1	Start a teacher action plan	The exam ID, while the job runs
2	Get the teacher action plan	A class overview, one action per question the class lost marks on, the learning outcomes assessed, and what each group of students needs	The teacher
3	Start a student action plan	The answer sheet ID, while the job runs
4	Get the student action plan	Next steps, a skill to focus on, and an encouraging tip	The student

Steps 1 and 2 run once per exam. Steps 3 and 4 run once per student.

Each call starts a background job. Wait until the job has finished before you show the plan. The wait_for helper below does this for you.

Set up

You need an access token. If you don’t have one, follow the Quickstart. You also need an exam whose answer sheets are evaluated. Action plans are built from the marks of each evaluated answer sheet, and from the answers that lost marks together with the feedback the evaluation left on them. See Get scores for review.

import time

import requests

BASE_URL = "https://api.crazygoldfish.com"
HEADERS = {"Authorization": "Bearer YOUR_ACCESS_TOKEN"}

EXAM_ID = "d19e6868-98dd-4274-a2a5-4a616dd93ea7"
DONE = ("Completed", "Partial")


def wait_for(path):
    """Check the plan every 5 seconds until the job finishes."""
    for _ in range(120):  # Give up after 10 minutes
        response = requests.get(BASE_URL + path, headers=HEADERS)
        response.raise_for_status()
        plan = response.json()["data"]
        if plan["status"] in DONE:
            return plan
        if plan["status"] == "Failed":
            raise RuntimeError(f"{path} failed")
        time.sleep(5)
    raise TimeoutError(f"{path} took longer than 10 minutes")

const BASE_URL = "https://api.crazygoldfish.com";
const HEADERS = { Authorization: "Bearer YOUR_ACCESS_TOKEN" };

const EXAM_ID = "d19e6868-98dd-4274-a2a5-4a616dd93ea7";
const DONE = ["Completed", "Partial"];

// Check the plan every 5 seconds until the job finishes
async function waitFor(path) {
  for (let i = 0; i < 120; i++) { // Give up after 10 minutes
    const response = await fetch(BASE_URL + path, { headers: HEADERS });
    if (!response.ok) throw new Error(await response.text());
    const { data } = await response.json();
    if (DONE.includes(data.status)) return data;
    if (data.status === "Failed") throw new Error(`${path} failed`);
    await new Promise((resolve) => setTimeout(resolve, 5000));
  }
  throw new Error(`${path} took longer than 10 minutes`);
}

Both GET endpoints return 200 for every status, including Failed. Always branch on data.status.

A plan reports one of four statuses:

`data.status`	Meaning	What to do
`In Progress`	The job is still running, and `action_plan` is an empty list	Poll again
`Completed`	The whole plan is ready	Show it
`Partial`	The plan is finished, but part of it is missing: some questions have no action, or, for a teacher plan, the class overview or the learning outcomes could not be written	Show what came back, or start the plan again. This is a finished job, so stop polling.
`Failed`	Nothing could be written. `action_plan` holds one entry with an `error`.	Start the plan again

That is why the helper above treats Partial as done. Both kinds of plan can report it.

Step 1: Start the teacher action plan

Send the exam’s UUID. The job reads every answer sheet in the exam, whatever the class size, and writes four things: a class overview, one action per question the class lost marks on, the learning outcomes the paper assesses, and what each score group of students needs. It usually takes one to three minutes.

response = requests.post(
    BASE_URL + "/action-plan/v1/k12/teacher",
    headers=HEADERS,
    json={"exam_id": EXAM_ID},
)
response.raise_for_status()

const started = await fetch(`${BASE_URL}/action-plan/v1/k12/teacher`, {
  method: "POST",
  headers: { ...HEADERS, "Content-Type": "application/json" },
  body: JSON.stringify({ exam_id: EXAM_ID }),
});
if (!started.ok) throw new Error(await started.text());

What you get back

{
  "detail": [
    {
      "id": "d19e6868-98dd-4274-a2a5-4a616dd93ea7",
      "msg": "Teacher action plan initiated successfully."
    }
  ]
}

id is the exam ID you sent, not a new job ID. Keep using the exam ID.

Step 2: Get the teacher action plan

Poll the same exam ID until the job finishes.

plan = wait_for(f"/action-plan/v1/k12/teacher/{EXAM_ID}")

overview = plan.get("overview", {})
print(overview.get("summary"))
for priority in overview.get("priorities", []):
    print(priority["title"], priority["question_numbers"])

for action in plan["action_plan"]:
    print(action["question_number"], action["action_type"], action["common_errors"])
    print(action["action"])

for group in plan.get("student_groups", []):
    names = [student["display_name"] for student in group["students"]]
    print(group["group_name"], names, group["action"])

const plan = await waitFor(`/action-plan/v1/k12/teacher/${EXAM_ID}`);

const overview = plan.overview ?? {};
console.log(overview.summary);
for (const priority of overview.priorities ?? []) {
  console.log(priority.title, priority.question_numbers);
}

for (const action of plan.action_plan) {
  console.log(action.question_number, action.action_type, action.common_errors);
  console.log(action.action);
}

for (const group of plan.student_groups ?? []) {
  const names = group.students.map((student) => student.display_name);
  console.log(group.group_name, names, group.action);
}

What you get back

{
  "data": {
    "id": "d19e6868-98dd-4274-a2a5-4a616dd93ea7",
    "exam_name": "Grade 10 Science Half Yearly",
    "status": "Completed",
    "created_at": "2026-09-17T11:24:38.512431",
    "overview": {
      "summary": "The class averaged 17.33 out of 40 (43.3%). No student could apply the thumb rule.",
      "strengths": ["Two of three students calculated the circuit quantities correctly."],
      "priorities": [
        {
          "title": "Applying the right-hand thumb rule",
          "insight": "Question 3 is worth 5 marks and the class averaged 1.67 on it.",
          "action": "Re-teach the rule on a straight wire, then on a loop.",
          "question_numbers": ["3"]
        }
      ],
      "class_stats": {
        "students_evaluated": 3,
        "total_marks": 40,
        "class_average_marks": 17.33,
        "class_average_percent": 43.3,
        "median_marks": 18,
        "highest_marks": 22,
        "lowest_marks": 12,
        "students_per_group": {"Needs support": 1, "Developing": 2, "Proficient": 0, "Advanced": 0}
      }
    },
    "action_plan": [
      {
        "question_number": "3",
        "students": ["S-1042", "S-1077", "S-1103"],
        "student_details": [
          {"student_id": "S-1042", "student_name": "Aarav Sharma", "display_name": "S-1042 - Aarav Sharma"},
          {"student_id": "S-1077", "student_name": "Diya Patel", "display_name": "S-1077 - Diya Patel"},
          {"student_id": "S-1103", "student_name": "Kabir Mehta", "display_name": "S-1103 - Kabir Mehta"}
        ],
        "overall_insight": "All three students described the field but none could apply the thumb rule.",
        "action_type": "Remediation",
        "action": "Re-teach the rule on a straight wire, then on a loop.",
        "common_errors": ["describes the field but does not apply the rule"],
        "max_marks": 5,
        "class_summary": {
          "students_counted": 3,
          "students_with_full_marks": 0,
          "students_with_partial_marks": 2,
          "students_with_zero_marks": 1,
          "students_not_attempted": 0,
          "average_marks": 1.67
        },
        "learning_outcome": "Applies the right-hand thumb rule to find the direction of a magnetic field"
      }
    ],
    "learning_outcomes": [
      {
        "learning_outcome": "Applies the right-hand thumb rule to find the direction of a magnetic field",
        "competency": "Application of concepts",
        "question_numbers": ["3"],
        "insight": "The class knows what the field looks like but cannot yet use the rule.",
        "action": "Practise the rule on three different conductor shapes."
      }
    ],
    "student_groups": [
      {
        "group_name": "Needs support",
        "score_range": "below 35%",
        "student_count": 1,
        "students": [
          {"student_id": "S-1077", "student_name": "Diya Patel", "display_name": "S-1077 - Diya Patel"}
        ],
        "group_average_percent": 30.0,
        "weakest_questions": [
          {"question_number": "3", "max_marks": 5, "group_average_marks": 0, "group_score_percent": 0.0}
        ],
        "insight": "This student scored nothing on the magnetic field question.",
        "action": "Work through the thumb rule one to one with a wire and a compass."
      }
    ]
  }
}

This example is shortened: a real plan has one action_plan entry per question the class lost marks on, and one student_groups entry per score group that has students. See Get a teacher action plan for every field.While the job runs, action_plan, learning_outcomes and student_groups are empty lists and overview is an empty object. action_type is Reinforcement, Remediation, or Extension.

Step 3: Start a student action plan

One call covers one student, so loop over the exam’s answer sheets. Get their IDs from List answer sheets.

ANSWER_SHEET_IDS = ["8a2f4c1e-5b3d-4e6f-9a7b-0c1d2e3f4a5b"]

for sheet_id in ANSWER_SHEET_IDS:
    response = requests.post(
        BASE_URL + "/action-plan/v1/k12/student",
        headers=HEADERS,
        json={"ans_sheet_id": sheet_id},
    )
    response.raise_for_status()

const ANSWER_SHEET_IDS = ["8a2f4c1e-5b3d-4e6f-9a7b-0c1d2e3f4a5b"];

for (const sheetId of ANSWER_SHEET_IDS) {
  const res = await fetch(`${BASE_URL}/action-plan/v1/k12/student`, {
    method: "POST",
    headers: { ...HEADERS, "Content-Type": "application/json" },
    body: JSON.stringify({ ans_sheet_id: sheetId }),
  });
  if (!res.ok) throw new Error(await res.text());
}

Step 4: Get the student action plans

Poll each answer sheet ID. The plan comes back as an array with one item in it.

for sheet_id in ANSWER_SHEET_IDS:
    result = wait_for(f"/action-plan/v1/k12/student/{sheet_id}")
    student_plan = result["action_plan"][0]
    print(result["student_name"], student_plan["skill_focus"])
    print(student_plan["action"])

for (const sheetId of ANSWER_SHEET_IDS) {
  const result = await waitFor(`/action-plan/v1/k12/student/${sheetId}`);
  const studentPlan = result.action_plan[0];
  console.log(result.student_name, studentPlan.skill_focus);
  console.log(studentPlan.action);
}

What you get back

{
  "data": {
    "id": "4b7f2a91-6c3d-4e58-9a2b-7d1e0c5f8a34",
    "status": "Completed",
    "student_id": "S-1042",
    "student_name": "Aarav Sharma",
    "created_at": "2026-09-17T11:31:02.884190",
    "action_plan": [
      {
        "overall_insight": "Aarav explains the idea but struggles to apply it.",
        "overall_action_type": "Remediation",
        "action": "Draw the diagram before writing each answer.",
        "skill_focus": "Application",
        "confidence_booster_tip": "You explain the idea well already.",
        "questions": [
          {
            "question_number": "3",
            "action_type": "Remediation",
            "action": "Practice the thumb rule on a wire, then on a loop."
          }
        ]
      }
    ]
  }
}

data.id is the plan’s own ID. No endpoint takes it, so keep using the answer sheet ID.

Good to know

Limits

Limit	Value
Source data	The marks of every evaluated answer sheet, and the answers that scored less than the full marks with the evaluation’s feedback
Optional questions	A question a student was allowed to skip, such as an either/or alternative or one of “any 8 of 12”, is not held against them
Language	A plan is written in the language of the question paper
Teacher plan	One call covers the whole exam, whatever the class size. The exam needs at least one answer sheet.
Student plan	One call covers one answer sheet
Starting plans	Daily limit per account. One counter covers the whole account and both POST endpoints share it, so teacher and student plans spend the same allowance. It resets at 00:01 server time.
Rejected requests	Still count. The counter is spent when the request arrives, before the exam or answer sheet is checked, so a request rejected with `400` uses up one of your calls.
Repeat calls	Allowed. Each call creates a new plan, and the GET call returns the newest one.
Visibility	You only see plans your own API user started

Use webhooks instead of polling

Plan	Event	`id` in the payload
Teacher	`teacher_action_plan`	The exam ID
Student	`student_action_plan`	The answer sheet ID

Both events are sent for Completed, Partial, and Failed, and only to an enabled webhook of the API user who started the plan. They carry an X-Webhook-Signature header you can verify. See Verify the signature.

Troubleshooting

Error	Fix
`422` `Value error, Exam with ID ... does not exist`	Use the exam `unique_id` from the Exam Evaluation API
`422` `Field required` for `ans_sheet_id`	Name the body field `ans_sheet_id`
The teacher plan request fails	The exam needs evaluated answer sheets. Add and evaluate them first.
The student plan request fails	Check the ID is the answer sheet ID you created the plan with.
`404` `Action plan not found ...`	Start the plan first, with the same API user
`429` `Daily rate limit exceeded`	Try again after 00:01 server time
`status` is `Failed`	Read `action_plan[0].error` for the reason in your logs, then start the plan again
`Completed` with an empty `action_plan`	No student lost marks in the exam, so there was nothing to plan
Still `In Progress` after 10 minutes	Start the plan again and contact us with the exam ID

Action Plans API reference

Every field, response, and error.

Evaluate an exam

Create the exam and evaluate the answer sheets first.

Teacher Action Plan

What teachers see, without the code.

Student Action Plan

What students see, without the code.

Get started

Guides

Exam Evaluation

Assignment Evaluation

Rubrics

Action Plans

Lesson Plan Builder

Worksheet Builder

ClassTrack

Metadata

Webhooks

Create action plans with the API

Set up

Step 1: Start the teacher action plan

Step 2: Get the teacher action plan

Step 3: Start a student action plan

Step 4: Get the student action plans

Good to know

Action Plans API reference

Evaluate an exam

Teacher Action Plan

Student Action Plan

​Set up

​Step 1: Start the teacher action plan

​Step 2: Get the teacher action plan

​Step 3: Start a student action plan

​Step 4: Get the student action plans

​Good to know

​Related

Action Plans API reference

Evaluate an exam

Teacher Action Plan

Student Action Plan

Set up

Step 1: Start the teacher action plan

Step 2: Get the teacher action plan

Step 3: Start a student action plan

Step 4: Get the student action plans

Good to know

Related