> 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/audits/read-an-audit.md).

# Read an audit

Use this endpoint to read an audit's requirement tree: the nested requirements, the rules on each, and which nodes are linked shared requirements. Every node's `id` is what the editing endpoints take, so read the draft before you edit it, and again to get the IDs of nodes you've added. `{audit_id}` is the audit's numeric ID from [`GET /programs/{program_short_name}/audits`](/stellic-partner-api/programs/list-a-program-s-audits.md), `new_audit_id`, or `draft_audit_id`.

## GET /audits/{audit\_id}

>

```json
{"openapi":"3.0.0","info":{"title":"Stellic for Developers","version":"1.0"},"tags":[{"name":"Audits","description":"Read, draft, edit, and publish an audit's requirement tree. Edits go to a draft; publishing recomputes student progress in the background."}],"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":{"AuditDetail":{"allOf":[{"$ref":"#/components/schemas/AuditSummary"},{"type":"object","properties":{"requirement_tree":{"$ref":"#/components/schemas/RequirementNode"},"shared_requirement_mapping":{"type":"object","description":"Keys are the `id` values (as strings) of the shared requirement nodes in `requirement_tree`; each value is the shared requirement program that node comes from.","additionalProperties":{"$ref":"#/components/schemas/ProgramSummary"}}}}]},"AuditSummary":{"type":"object","properties":{"id":{"type":"integer","description":"Internal database ID of the audit. Use it on the `/audits/` endpoints."},"name":{"type":"string","description":"Audit name. A draft created from a published audit carries the published name plus a `-draft` suffix until it is published."},"status":{"type":"string","description":"One of `draft`, `review`, `published`. Other statuses exist internally but are not served.","enum":["draft","review","published"]}}},"RequirementNode":{"type":"object","description":"One requirement in an audit tree. Sub-requirements nest under `choices`. Course nodes carry only `id`, `screen_name`, `course_parent_id`, and `constraints`.","properties":{"id":{"type":"integer","description":"Internal database ID of the requirement. This is the value for `parent_req_id`, `subrequirement_id`, and `requirement_id` on the editing endpoints."},"screen_name":{"type":"string","description":"Display name. For the root node this is the program name; for a course node it is the course code."},"original_min_units":{"type":"number","nullable":true,"description":"Minimum units as originally configured, or `null`."},"min_units":{"type":"number","nullable":true,"description":"Minimum units currently applied to this requirement, or `null`."},"is_shared":{"type":"boolean","description":"`true` when this node is a shared requirement linked from another program. Its entry in `shared_requirement_mapping` names that program."},"is_uni_req":{"type":"boolean","description":"`true` when the shared requirement is a university-wide requirement."},"is_concentration":{"type":"boolean","description":"`true` for a concentration parent, whose children are the program's concentrations."},"concentration_type":{"type":"string","description":"Display name of the concentration type (not its `external_id`). Present only when `is_concentration` is `true`."},"default_concentration":{"type":"boolean","description":"`true` for the default child of a concentration parent."},"is_text":{"type":"boolean","description":"Present (and `true`) only for text-only requirements."},"is_check":{"type":"boolean","description":"Present (and `true`) only for check-box requirements."},"is_free_elective":{"type":"boolean","description":"Present (and `true`) only for the free-electives requirement."},"course_parent_id":{"type":"string","description":"Course nodes only. A 20-digit composite of the parent's ID and the course requirement's ID. It is not a database ID; use the node's `id` on the editing endpoints."},"choices":{"type":"array","description":"Sub-requirements, in display order. Absent on course nodes.","items":{"$ref":"#/components/schemas/RequirementNode"}},"constraints":{"type":"array","description":"Rules on this requirement, in evaluation order.","items":{"$ref":"#/components/schemas/RequirementConstraint"}},"uid":{"type":"string","description":"Cache token present only on a node returned as a tree root. Ignore it."}}},"RequirementConstraint":{"type":"object","description":"One rule on a requirement.","properties":{"id":{"type":"integer","description":"Internal database ID of the constraint; the `constraint_id` for update and remove calls."},"type":{"type":"string","description":"Constraint type name, for example `anyxof`, `minxunits`, `minxcourses`, `mingrade`, `notcount`, `xfromdepts`, `coderange`."},"type_string":{"type":"string","description":"Human-readable rendering of the rule. Present for most constraint types."},"data":{"type":"object","description":"Type-specific fields, in the same shape you send on the add and update calls. For `minxunits` that is `units` and `is_each`; for `anyxof` it is `x` and `is_and`."},"is_hidden":{"type":"boolean","description":"Whether the constraint is hidden from students in the audit view."}}},"ProgramSummary":{"type":"object","description":"A program as the programs and audits endpoints return it.","properties":{"id":{"type":"integer","description":"Internal database ID of the program. Only needed where an endpoint asks for it, such as `base_program`."},"name":{"type":"string"},"external_id":{"type":"string","description":"The program's `short_name`, the identifier you use in path parameters and in your program feed. For a shared requirement program it equals `name`."},"shared_requirement":{"type":"object","description":"Present only for programs of type `shared requirement`. `id` is the value to send as `shared_requirement_id` when linking this shared requirement into an audit.","properties":{"id":{"type":"integer"}}}}}}},"paths":{"/audits/{audit_id}":{"get":{"tags":["Audits"],"parameters":[{"name":"audit_id","in":"path","required":true,"description":"Internal numeric ID of the audit, as returned in `audits[].id` by `GET /programs/{program_short_name}/audits`, in `new_audit_id`, or in `draft_audit_id`. A non-numeric value does not match the route and returns a plain 404.","schema":{"type":"integer"}}],"responses":{"200":{"description":"Audit found. `requirement_tree` is the full tree: the root's `screen_name` is the program name, `choices` nests sub-requirements, and every node's `id` is the value you use as `parent_req_id`, `subrequirement_id`, or `requirement_id` on the editing endpoints. `shared_requirement_mapping` maps the `id` of each shared requirement node in this tree to the shared requirement program it comes from.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuditDetail"}}}},"401":{"description":"Missing or invalid Bearer token.","content":{"application/json":{"schema":{"type":"object","properties":{"detail":{"type":"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. Also returned, with only `error` set, when the audit is archived or a snapshot (`This audit is not available for partner API`) or belongs to a compliance requirement (`Compliance requirements are not available via the API.`).","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"},"client_ip":{"type":"string"}}}}}},"404":{"description":"No audit has this ID.","content":{"application/json":{"schema":{"type":"object","properties":{"detail":{"type":"string"}}}}}}}}}}}
```

#### Notes

* **A draft has its own requirement IDs.** Only course nodes keep theirs. Take IDs from the draft you're editing, never from the published audit.
* **`requirement_tree` nests through `choices`.** The root's `screen_name` is the program name. Course nodes carry only `id`, `screen_name` (the course code), `constraints`, and `course_parent_id`, a composite of the parent's and the course's IDs. Use `id` on the editing endpoints, not `course_parent_id`.
* **A course node has the same `id` in every audit that lists it.**
* **`shared_requirement_mapping` maps each linked shared requirement's node `id`** (as a string) to the shared requirement program it comes from.
* **Only draft, under-review, and published audits are served.** Archived versions and snapshots return a 403 with `This audit is not available for partner API`, and a compliance requirement's audit returns a 403 with `Compliance requirements are not available via the API.`

#### Related APIs

* [`POST /audits/{audit_id}/draft`](/stellic-partner-api/audits/get-or-create-a-draft-of-a-published-audit.md) to get the editable draft of a published audit.
* [`POST /audits/{audit_id}/requirements/{parent_req_id}/subrequirements`](/stellic-partner-api/audits/add-a-sub-requirement.md) to add under a node.
* [`POST /requirements/{requirement_id}/constraints`](/stellic-partner-api/requirements/add-a-constraint-to-a-requirement.md) to add a rule to a node.