> 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/read-a-student-s-gpas.md).

# Read a student's GPAs

Use this endpoint to read a student's GPAs: the cumulative GPA, the GPA for each declared program, and GPAs on individual requirements, plus any GPAs your institution defines. They come from the student's official audit as Stellic last saved it, the same values advisors filter on in search. The cumulative GPA is the one your data sync sends for the student's latest term. Narrow the lists with `type` (case-insensitive) and `requirement_id`.

## GET /student/{student\_username}/gpas

>

```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":{"StudentGpasResponse":{"type":"object","properties":{"success":{"type":"boolean"},"cumulative_gpas":{"type":"array","description":"The cumulative GPA your data sync sends for the student's latest term, plus any institution-defined cumulative GPAs. Empty when the saved audit has no cumulative GPA.","items":{"$ref":"#/components/schemas/CumulativeGpaEntry"}},"program_gpas":{"type":"array","description":"One entry per GPA computed at the top of a program's audit, including institution-defined GPAs at that level. Empty when no program on the student's plan carries a GPA.","items":{"$ref":"#/components/schemas/ProgramGpaEntry"}},"requirement_gpas":{"type":"array","description":"One entry per GPA computed on a requirement below the program level (for example a major-core GPA), including institution-defined GPAs on that requirement. The program-level GPA itself is reported under `program_gpas`, not here.","items":{"$ref":"#/components/schemas/RequirementGpaEntry"}}}},"CumulativeGpaEntry":{"type":"object","properties":{"value":{"type":"number","description":"The GPA. For the built-in cumulative GPA this is never `null`; institution-defined entries can carry `null` when no value has been computed."},"diff":{"type":"number","nullable":true,"description":"Change in this GPA compared with the previous term; `null` when there is no previous term to compare against."},"type_name":{"type":"string","description":"`CUMULATIVE` for the built-in cumulative GPA; otherwise the institution-defined GPA name in upper case."},"year":{"type":"integer","nullable":true,"description":"Year of the term the cumulative GPA is current through. `null` on institution-defined entries and when the term cannot be resolved."},"semester":{"type":"integer","nullable":true,"description":"Internal identifier of the term name (for example the row for a spring term) the cumulative GPA is current through. Use `semester_ref` when you need to order terms. `null` on institution-defined entries."},"semester_ref":{"type":"string","nullable":true,"description":"Sortable term reference: the year followed by the term's position within the year, zero-padded to four digits (for example `20250002`). `null` on institution-defined entries."}}},"ProgramGpaEntry":{"type":"object","properties":{"value":{"type":"number","nullable":true,"description":"The GPA computed at the top of this program's audit."},"program_id":{"type":"integer","description":"Internal database ID of the program. Not the identifier you use on the program enrollment endpoints; see `program_external_id` for that."},"type_name":{"type":"string","description":"`PROGRAM` for the built-in program GPA; otherwise the institution-defined GPA name in upper case."},"program_name":{"type":"string","nullable":true,"description":"Display name of the program."},"program_external_id":{"type":"string","nullable":true,"description":"The program's `short_name`, the same value you pass as `{program_id}` on `/planner/enrollment/program/{username}/{program_id}`."}}},"RequirementGpaEntry":{"type":"object","properties":{"requirement_id":{"type":"string","description":"Internal ID of the requirement, returned as a string even though the `requirement_id` query filter takes an integer."},"value":{"type":"number","nullable":true,"description":"The GPA computed on this requirement."},"type_name":{"type":"string","description":"`REQUIREMENT` for the built-in requirement GPA; otherwise the institution-defined GPA name in upper case."},"program_name":{"type":"string","description":"Display name of the program whose audit contains this requirement."},"requirement_screen_name":{"type":"string","description":"The requirement's display name as it appears in the audit."}}}}},"paths":{"/student/{student_username}/gpas":{"get":{"tags":["Student"],"parameters":[{"name":"student_username","in":"path","required":true,"description":"Student's platform username. Matched exactly as stored; this path does not lowercase the value. Archived students are accepted and return the GPAs from their audit as saved at archive.","schema":{"type":"string"}},{"name":"type","in":"query","required":false,"description":"Case-insensitive filter on `type_name`, applied to all three lists at once. Built-in values are `CUMULATIVE`, `PROGRAM`, and `REQUIREMENT`; GPAs your institution defines carry their configured name in upper case. Passing `CUMULATIVE` therefore empties `program_gpas` and `requirement_gpas`. An empty value matches nothing.","schema":{"type":"string"}},{"name":"requirement_id","in":"query","required":false,"description":"Keep only the `requirement_gpas` entry for this requirement (the platform's internal requirement ID, a number). `cumulative_gpas` and `program_gpas` are returned in full regardless. Must be an integer; an empty or non-numeric value returns `400`.","schema":{"type":"integer"}}],"responses":{"200":{"description":"Success. Three lists, each possibly empty. Values come from the student's official audit (graded and registered courses only) as Stellic last saved it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StudentGpasResponse"}}}},"400":{"description":"Two causes, same envelope `{\"errors\": [{\"message\": \"...\"}]}`:\n\n- `requirement_id` is empty or not an integer. The message is the literal string `['requirement_id must be an integer']`, brackets and quotes included.\n- The student's audit has no GPA data. The message is `Audit Cache has not been populated for this student yet`.","content":{"application/json":{"schema":{"type":"object","properties":{"errors":{"type":"array","items":{"type":"object","properties":{"message":{"type":"string"}}}}}}}}},"401":{"description":"Missing or invalid Bearer token."},"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":"Three causes, same envelope `{\"errors\": [{\"message\": \"...\"}]}`:\n\n- Student not found: `Student with username 'jdoe' not found`.\n- Student has no default plan: `No default plan found for student 'jdoe'`.\n- Stellic hasn't saved an official audit for the student: `'Audit not found or Audit progress has not been populated for this student'`. The single quotes around this message are part of the JSON string.","content":{"application/json":{"schema":{"type":"object","properties":{"errors":{"type":"array","items":{"type":"object","properties":{"message":{"type":"string"}}}}}}}}},"500":{"description":"Unhandled error. Body is `{\"errors\": []}` with an empty array; treat it as opaque and log the HTTP code.","content":{"application/json":{"schema":{"type":"object","properties":{"errors":{"type":"array","description":"Always an empty array on this endpoint.","items":{"type":"object"}}}}}}}}}}}}
```

#### Notes

* **`type` narrows all three lists; `requirement_id` narrows only `requirement_gpas`.** An unknown `type` returns empty lists, not an error.
* **Use `program_external_id` to match programs.** `program_id` is Stellic's internal ID. The program enrollment endpoints take the short name, which is `program_external_id`.
* **If Stellic hasn't saved an official audit for the student, you get a 404** `'Audit not found or Audit progress has not been populated for this student'`, with the quotes as part of the message.
* **Archived students return the GPAs from their audit as saved at archive.**
* **Usernames must match exactly** and aren't lowercased. A student without a default plan returns a 404.

#### Related APIs

* [`GET /student/{student_username}/progress/summary`](/stellic-partner-api/student/read-a-student-s-progress-summary.md) for completion percentages.
* [`GET /student/{student_username}/audit/official/{course_filter}/{property}`](/stellic-partner-api/student/read-a-student-s-official-degree-audit.md) for the full audit.