> For the complete documentation index, see [llms.txt](https://docs.stellic.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.stellic.com/stellic-partner-api/student/run-a-what-if-audit-for-a-student.md).

# Run a what-if audit for a student

Use this endpoint to see how a student's courses would count against a different set of programs, for example registered courses against every program on the plan, without changing their enrollments. It works like [the official audit](/stellic-partner-api/student/read-a-student-s-official-degree-audit.md), except that you pick the courses and the programs separately: `{course_filter}` is `registered` or `planned`, and `{program_filter}` is `registered` (declared programs), `planned` (programs on the plan, declared or not), or `all` (every program on the default plan).

## GET /student/{student\_username}/audit/official/custom/{course\_filter}/{program\_filter}/{property}

>

```json
{"openapi":"3.0.0","info":{"title":"Stellic for Developers","version":"1.0"},"tags":[{"name":"Student"}],"servers":[{"url":"https://{institution}.stellic.com/partnerapi/v1","variables":{"institution":{"default":"{institution}","description":"Your institution's Stellic subdomain: the part before `.stellic.com` in the URL you use to sign in. It becomes the host in every request, as in `https://{institution}.stellic.com/partnerapi/v1/...`. Replace the `{institution}` placeholder with your subdomain before sending."}}}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token issued by your Stellic integration partner. Send it as `Authorization: Bearer <token>` on every request. One token per institution; do not share across environments."}},"schemas":{"UnmatchedCourses":{"type":"object","properties":{"unmatched_courses":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string","description":"Course code."},"units":{"type":"number","nullable":true,"description":"Student-specific units for this plan course (may differ from catalog units after split credits or transfer awards). `null` when no units are set."},"sections":{"type":"array","items":{"type":"string","nullable":true},"description":"SIS section IDs of the sections linked to this plan course. An entry is `null` when the section has no SIS ID."},"grade":{"type":"string","nullable":true},"mid_semester_grade":{"type":"string","nullable":true},"grade_option":{"type":"string","nullable":true},"is_transfer":{"type":"boolean"},"transfer_university":{"type":"string","nullable":true},"registration_status":{"type":"string","nullable":true,"description":"Name of the registration status (e.g., enrolled, waitlisted). `null` when the course has no registration record."},"repeat_code":{"type":"string","nullable":true},"attributes":{"type":"array","items":{"type":"string"}},"tags":{"type":"array","items":{"type":"string"},"description":"External tag names attached to this plan course."},"enrollment_level":{"type":"string","nullable":true,"description":"Enrollment level name, or `null` if not set or marked internal."},"course_topic":{"type":"string","nullable":true,"description":"Topic name when the course is a registered topic course; otherwise `null`."},"is_residency":{"type":"boolean"},"is_exam":{"type":"boolean"},"cross_course_link_destination_ids":{"type":"array","items":{"type":"integer"},"description":"Internal plan-course IDs this course links forward to. Useful for cross-course relationships within the plan."},"cross_course_link_source_ids":{"type":"array","items":{"type":"integer"},"description":"Internal plan-course IDs this course links back from."},"version_id":{"type":"integer","description":"Present only when this plan course points at a specific catalog version of the course."}}}},"counts_for":{"type":"array","items":{"type":"string"},"description":"Always an empty array."},"success":{"type":"boolean"}}},"AuditProgress":{"type":"object","properties":{"audit_dict":{"type":"object","properties":{"VERSION":{"type":"string"},"courses_summary":{"type":"object","properties":{"unplanned":{"type":"integer"},"taking":{"type":"integer"},"unmatched":{"type":"integer"},"planned":{"type":"integer"},"taken":{"type":"integer"},"registered":{"type":"integer"}}},"unmatched_slots":{"type":"array","items":{"type":"object"}},"course_plan_info":{"type":"object"},"satisfied":{"type":"boolean"},"unmatched":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"id":{"type":"integer"},"rr":{"type":"boolean"}}}},"placeholders_info":{"type":"object"},"cards":{"type":"array","items":{"type":"object","properties":{"is_course":{"type":"boolean"},"req_name":{"type":"string"},"req_units":{"type":"number"},"req_id":{"type":"integer"}}}},"grades_summary":{"type":"object","properties":{"requirement_custom_gpas":{"type":"object"},"custom_c_gpas":{"type":"array","items":{"type":"string"}},"semester_gpa":{"type":"object","properties":{"semester":{"type":"object","properties":{"semester":{"type":"integer"},"year":{"type":"integer"}}},"gpa_diff":{"type":"number"},"gpa":{"type":"number"}}},"cgpa_semester":{"type":"object","properties":{"semester":{"type":"integer"},"year":{"type":"integer"}}},"c_gpa":{"type":"number"},"requirement_gpa":{"type":"object"},"cgpa_diff":{"type":"number"}}},"requirement_dict":{"type":"object"},"milestones_summary":{"type":"object"},"full_gpa":{"type":"object"},"units_summary":{"type":"object","properties":{"unplanned":{"type":"integer"},"taking":{"type":"integer"},"unmatched":{"type":"integer"},"planned":{"type":"integer"},"taken":{"type":"integer"},"registered":{"type":"integer"}}}}},"success":{"type":"boolean"},"req_tree":{"type":"object","description":"One combined requirement tree for all the programs audited, not one tree per program.","properties":{"programs":{"type":"array","items":{"type":"object","properties":{"default_concentration":{"type":"boolean"},"is_concentration":{"type":"boolean"},"is_uni_req":{"type":"boolean"},"is_shared":{"type":"boolean"},"choices":{"type":"array","items":{"type":"object"}}}}},"constraints":{"type":"array","items":{"type":"object"}},"id":{"type":"integer"},"screen_name":{"type":"string"}}}}}}},"paths":{"/student/{student_username}/audit/official/custom/{course_filter}/{program_filter}/{property}":{"get":{"tags":["Student"],"parameters":[{"name":"student_username","in":"path","required":true,"description":"Student's Stellic username.","schema":{"type":"string"}},{"name":"course_filter","in":"path","required":true,"description":"Picks which courses to audit.\n\n- `registered`: graded and registered courses in any term (waitlisted and cart courses excluded), counting only courses that can count.\n- `planned`: every course on the default plan except removed courses and waitlisted courses in past terms.","schema":{"type":"string","enum":["registered","planned"]}},{"name":"program_filter","in":"path","required":true,"description":"Picks which programs to audit against, independently of `course_filter`.\n\n- `registered`: declared programs only.\n- `planned`: every program currently on the student's plan, declared or not.\n- `all`: every program attached to the student's default plan, including programs the student removed from view.\n\nPrograms without an audit are skipped for all three values.","schema":{"type":"string","enum":["registered","planned","all"]}},{"name":"property","in":"path","required":true,"description":"- `unmatched`: the courses that didn't satisfy any requirement under the chosen filter combination.\n- `progress`: the full audit document (`audit_dict`) plus one combined requirement tree (`req_tree`) for all the programs audited. For completion percentages against declared programs, use `GET /student/{student_username}/progress/summary` instead.","schema":{"type":"string","enum":["unmatched","progress"]}}],"responses":{"200":{"description":"What-if audit result, computed when you call and not saved. Shape depends on `property`: `unmatched` returns `UnmatchedCourses`, `progress` returns `AuditProgress`.","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/UnmatchedCourses"},{"$ref":"#/components/schemas/AuditProgress"}]}}}},"400":{"description":"Invalid path parameter, or the cached audit is missing required data. Body is `{\"errors\": [{\"message\": \"...\"}]}`.\n\nMessages you'll see:\n- Invalid `property`: `b\"The parameter 'property' has an invalid value. 'property' can only be one of the following: unmatched, progress\"` (the two values can be listed in either order).\n- Invalid `course_filter`: `b'Invalid \\`course_filter\\`, supported modes are: registered, planned'`\n- Invalid `program_filter`: `b'Invalid \\`program_filter\\`, supported modes are: registered, planned, all'`\n- Missing `unmatched` data when `property=unmatched`: `Audit Cache has not been populated for this student yet`.\n\nThe `property`, `course_filter`, and `program_filter` messages come back wrapped as a bytes literal: `b\"...\"` for the `property` message, which contains single quotes, and `b'...'` for the others. The prefix and quotes are part of the JSON string."},"403":{"description":"Your IP address isn't on the allowlist for this endpoint. Contact Stellic to add it; the response includes the `client_ip` Stellic saw.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"},"client_ip":{"type":"string"}}}}}},"404":{"description":"Body is `{\"errors\": [{\"message\": \"...\"}]}`. Causes:\n\n- Student not found: `Student with username '<username>' not found`.\n- Student without a default plan: `Student with username '<username>' does not have a plan`.\n- Stellic couldn't produce an audit for the student's default plan: `'Audit not found for the student'`. The single quotes around the message are part of the JSON string; strip them on your side if you display the message."},"500":{"description":"Unhandled error. Body is `{\"errors\": []}` (empty array), not a parseable message. Causes include unexpected errors while computing or formatting the audit."}}}}}}
```

#### What happens after the call

* The audit is computed when you call and isn't saved. Enrollments, declarations, and the audit students and advisors see in Stellic are unchanged.

#### Notes

{% hint style="warning" %}
**At institutions that track degree requirements, a what-if audit can change the student's degree audit.** When the student has a credential on their plan, the degree requirements are rebuilt for the programs you picked, and audit exceptions that don't fit the new requirements can be marked removed. Don't run what-if audits for students with exceptions on their degree requirements.
{% endhint %}

* **The rules on the official audit page apply here too**: which courses are included, slow responses, locked programs, the empty `counts_for`, and the 404 for a student without a default plan.

#### Related APIs

* [`GET /student/{student_username}/audit/official/{course_filter}/{property}`](/stellic-partner-api/student/read-a-student-s-official-degree-audit.md) for the student's audit with the programs matched to the courses.
* [`POST /planner/enrollment/program/{username}/{program_id}`](/stellic-partner-api/program-enrollments/enroll-a-student-in-a-program.md) to add a program to the plan.