> ## Documentation Index > Fetch the complete documentation index at: https://docs.agentscope.io/llms.txt > Use this file to discover all available pages before exploring further. # Probe the session's high-level status > Return the unified :class:`SessionStatus` for a session. Ownership validation, cluster-liveness probing, and parked-state derivation are all delegated to :meth:`SessionService.get_session_status` — see that method for the precedence rules that collapse the two orthogonal signals (message-bus run lock + persisted context tail) into a single four-valued enum. Args: session_id (`str`): The session to probe. agent_id (`str`): The agent that owns the session (ownership validation). user_id (`str`): Injected authenticated user ID. session_service (`SessionService`): Injected session service. Owns both storage and message bus dependencies so the composed answer is derived in a single layer. Returns: `SessionStatusResponse`: The probed session id and its unified status. Raises: `HTTPException`: 404 if the session does not exist or does not belong to the authenticated user. ## OpenAPI ````yaml /versions/2.0.4/en/deploy/openapi.json get /sessions/{session_id}/status openapi: 3.1.0 info: title: AgentScope version: 2.0.4 servers: [] security: [] paths: /sessions/{session_id}/status: get: tags: - sessions summary: Probe the session's high-level status description: |- Return the unified :class:`SessionStatus` for a session. Ownership validation, cluster-liveness probing, and parked-state derivation are all delegated to :meth:`SessionService.get_session_status` — see that method for the precedence rules that collapse the two orthogonal signals (message-bus run lock + persisted context tail) into a single four-valued enum. Args: session_id (`str`): The session to probe. agent_id (`str`): The agent that owns the session (ownership validation). user_id (`str`): Injected authenticated user ID. session_service (`SessionService`): Injected session service. Owns both storage and message bus dependencies so the composed answer is derived in a single layer. Returns: `SessionStatusResponse`: The probed session id and its unified status. Raises: `HTTPException`: 404 if the session does not exist or does not belong to the authenticated user. operationId: get_session_status_sessions__session_id__status_get parameters: - name: session_id in: path required: true schema: type: string title: Session Id - name: agent_id in: query required: true schema: type: string description: Agent the session belongs to. title: Agent Id description: Agent the session belongs to. - name: x-user-id in: header required: true schema: type: string description: >- Caller's user ID. Temporary header-based identity; will be replaced by JWT auth. title: X-User-Id description: >- Caller's user ID. Temporary header-based identity; will be replaced by JWT auth. responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/SessionStatusResponse' '404': description: Not found '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' components: schemas: SessionStatusResponse: properties: session_id: type: string title: Session Id description: The session that was probed. status: $ref: '#/components/schemas/SessionStatus' description: >- The session's unified status. One of ``running`` (some worker holds the run lease), ``idle`` (no worker, context clean), ``awaiting_permission`` (no worker, context parked on HITL tool call), or ``awaiting_external_result`` (no worker, context parked on external executor). type: object required: - session_id - status title: SessionStatusResponse description: |- Response body for probing a session's high-level status. See :class:`~agentscope.app._service.SessionStatus` for the semantics of each ``status`` value and the precedence rules used to derive it. HTTPValidationError: properties: detail: items: $ref: '#/components/schemas/ValidationError' type: array title: Detail type: object title: HTTPValidationError SessionStatus: type: string enum: - running - idle - awaiting_permission - awaiting_external_result title: SessionStatus description: |- The high-level status of a session, unifying cluster liveness (from the message bus) with the durable tool-call parking state (from the persisted :class:`~agentscope.state.AgentState.context`). Exactly one value applies at any moment — the frontend renders a single indicator without having to reconcile multiple boolean flags. Precedence: ``RUNNING`` is decided first from the distributed session-run lock; only when the session is not held by any worker do the ``AWAITING_*`` / ``IDLE`` values (derived from the stored context tail) apply. This ordering reflects the ground-truth hierarchy — while a worker owns the run, the live in-memory state supersedes the persisted snapshot, which is by definition stale until the run yields. Values: - ``RUNNING``: a worker somewhere in the cluster currently holds the session's run lease on the message bus. - ``IDLE``: no worker is running the session, and its persisted context is not parked on any pending tool call. - ``AWAITING_PERMISSION``: no worker is running the session, and the persisted context tail has at least one tool call waiting for user permission confirmation (HITL). - ``AWAITING_EXTERNAL_RESULT``: no worker is running the session, and the persisted context tail has at least one tool call dispatched to an external executor and awaiting its result (with no peer awaiting permission). ValidationError: properties: loc: items: anyOf: - type: string - type: integer type: array title: Location msg: type: string title: Message type: type: string title: Error Type input: title: Input ctx: type: object title: Context type: object required: - loc - msg - type title: ValidationError ````