---
title: "Get Schedule Status"
method: GET
path: "/schedules/{schedule_id}/status"
---

# Get Schedule Status

`GET /schedules/{schedule_id}/status`

Report live generation state, API safeguards, and terminal reason for a session.

Args:
    schedule_id: Unique identifier of the session to inspect.

Returns:
    A non-blocking operational snapshot including initialization/background
    states, idle age, counts, completion metadata, and configured limits.

Raises:
    HTTPException: Status 404 when the session does not exist.

Behavior:
    State is derived from futures, tasks, exhaustion, and retained counts without
    invoking the solver or generator. The query refreshes the session access
    timestamp before the response is built, so reported idle time is near zero.

## Path parameters

- `schedule_id` string, required

## Response `200`

Successful Response

- SessionDiagnosticResponse — Operational state, resource safeguards, and completion metadata for a session. Fields: schedule_id: Unique identifier for the generation session. state: Overall state: initializing, generating, complete, or ready. background_state: Lifecycle state of the generate-all background task. background_error: Last background failure text, if generation failed. completion_reason: Machine-oriented explanation for terminal generation. generated_schedules: Number of schedules currently retained. requested_schedule_limit: Client-requested maximum enumeration count. enumeration_scope: Whether results exhausted the space, stopped at the requested bound, or remain indeterminate. known_distinct_schedules: Distinct schedules observed in this session. idle_seconds: Rounded seconds since the session was last accessed. session_ttl_seconds: Configured idle expiry threshold. solver_timeout_ms: Configured timeout for each solver check. max_courses: Configured course-count submission limit. max_candidate_slots: Configured candidate-slot estimate limit. max_schedules_per_session: Configured per-session enumeration limit.
  - `schedule_id` string, required
  - `state` 'initializing' | 'generating' | 'complete' | 'ready', required
  - `background_state` 'not_started' | 'running' | 'cancelled' | 'failed' | 'completed', required
  - `background_error` string, nullable, required
  - `completion_reason` string, nullable, required
  - `generated_schedules` integer, required
  - `requested_schedule_limit` integer, required
  - `enumeration_scope` 'exhausted' | 'bounded_by_requested_limit' | 'indeterminate', required
  - `known_distinct_schedules` integer, required
  - `idle_seconds` integer, required
  - `session_ttl_seconds` integer, required
  - `solver_timeout_ms` integer, required
  - `max_courses` integer, required
  - `max_candidate_slots` integer, required
  - `max_schedules_per_session` integer, required

## Other responses

- `422` — Validation Error

---

[API](https://skmtc.net/mucsci/apis/course-scheduler-api.md) · [All operations](https://skmtc.net/mucsci/apis/course-scheduler-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/mucsci/course-scheduler-api/revisions/f728bfcee693/schema)