> ## Documentation Index
> Fetch the complete documentation index at: https://developer.eka.care/llms.txt
> Use this file to discover all available pages before exploring further.

# Get Session

> Retrieve the current status of a session and, once processing finishes, its transcript and structured template results. The **HTTP status code** signals progress: `202` still processing, `200` completed, `206` completed with partial results, `410` expired, `404` not found. After calling End Session, poll this endpoint at ~1-second intervals until the status is no longer `202`.


Retrieve the current status of a session and — once processing finishes — its transcript and structured template results. This is the endpoint you **poll** after [End Session](/api-reference/health-ai/ekascribe/protocol/end-session).

<Info>
  The **HTTP status code is the signal**. The same endpoint returns different status codes and response shapes depending on where the session is in its lifecycle.
</Info>

## Polling guidance

After you receive `202 Accepted` from End Session, poll this endpoint at **\~1-second intervals** until the status is no longer `202`:

```
POST /voice/v1/sessions/{session_id}/end        → 202 Accepted
GET  /voice/v1/sessions/{session_id}            → 202  (wait 1s, retry)
GET  /voice/v1/sessions/{session_id}            → 202  (wait 1s, retry)
GET  /voice/v1/sessions/{session_id}            → 200  ✓ results ready
```

<Tip>
  Prefer not to poll? Register a [webhook](/api-reference/connect/webhooks/register-webhook) to be notified automatically when processing completes, and call Get Session once on receipt.
</Tip>

## Status codes

| HTTP status | `status`                     | Meaning                                                         | Body                             |
| ----------- | ---------------------------- | --------------------------------------------------------------- | -------------------------------- |
| `202`       | `processing` / `initialized` | Still processing — keep polling.                                | `SessionProcessingResponse`      |
| `200`       | `completed`                  | Finished successfully; transcript + templates available.        | `SessionCompletedResponse`       |
| `206`       | `partial`                    | Finished, but some templates failed.                            | `SessionPartialResponse`         |
| `200`       | `failed`                     | Processing failed (terminal). Inspect the response for details. | `SessionCompletedResponse` shape |
| `410`       | `expired`                    | Session expired before processing was initiated.                | `ExpiredSessionResponse`         |
| `404`       | —                            | Session does not exist.                                         | `ErrorResponse`                  |

## Response fields by state

Every state also echoes `upload_url` (the session's audio upload endpoint — HTTPS for chunked, `wss://` for stream).

### `202` Processing

`session_id`, `status`, `created_at`, `expires_at`, `audio_files_received`, `audio_files[]`, `additional_data`, `transcript` (partial/empty), `patient_details`.

### `200` Completed

Adds `completed_at`, `model_used`, `language_detected`, the full `transcript`, and `templates` — an array with one entry per generated document, keyed by `template_id` (each entry carries `status`, `data`, `document_id`, `publish` metadata, and a `presigned_url` when applicable).

### `206` Partial

Same as completed, plus `audio_files_processed` and `processing_errors[]` describing the non-fatal failures.

### `410` Expired

`session_id`, `status: expired`, `created_at`, `expired_at`, `message`, `audio_files_received`, `audio_files[]`, empty `templates`/`transcript`.

## Filtering to one template

Pass `?template_id=<id>` to restrict the returned `templates` to documents for a single template only — useful when a session requested multiple templates but you only need one.


## OpenAPI

````yaml GET /voice/v1/sessions/{session_id}
openapi: 3.0.1
info:
  title: EkaScribe Protocol API (MedScribeAlliance v0.1)
  version: '0.1'
  description: >
    Session-based medical voice capture API implementing the MedScribeAlliance
    Protocol v0.1. Discover service capabilities, create a session, stream audio
    chunks, then end the session to trigger asynchronous transcription and
    structured-template extraction.
servers:
  - url: https://api.eka.care
    description: Production server
  - url: https://api.dev.eka.care
    description: Development server
security: []
paths:
  /voice/v1/sessions/{session_id}:
    get:
      tags:
        - protocol
      summary: Get Session
      description: >
        Retrieve the current status of a session and, once processing finishes,
        its transcript and structured template results. The **HTTP status code**
        signals progress: `202` still processing, `200` completed, `206`
        completed with partial results, `410` expired, `404` not found. After
        calling End Session, poll this endpoint at ~1-second intervals until the
        status is no longer `202`.
      parameters:
        - name: session_id
          in: path
          required: true
          description: Session ID returned by Create Session
          schema:
            type: string
            example: ses_abc123def456
        - name: template_id
          in: query
          required: false
          description: >-
            If provided, restricts returned templates to documents for this
            template_id only.
          schema:
            type: string
      responses:
        '200':
          description: Session completed successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SessionCompletedResponse'
              example:
                session_id: ses_abc123def456
                status: completed
                created_at: '2026-06-06T14:21:07Z'
                completed_at: '2026-06-06T14:21:34Z'
                expires_at: '2026-06-06T15:21:07Z'
                upload_url: https://api.eka.care/voice/v1/sessions/ses_abc123def456/audio
                model_used: pro
                language_detected: en
                audio_files_received: 4
                audio_files:
                  - 0.wav
                  - 1.wav
                  - 2.wav
                  - 3.wav
                additional_data:
                  _protocol:
                    version: '0.1'
                    upload_type: chunked
                    communication_protocol: http
                    requested_templates:
                      - eka_emr_template
                      - clinical_notes_template
                transcript: Patient presents with cough and fever...
                templates:
                  - eka_emr_template:
                      status: success
                      document_id: doc_abc123
                      document_type: eka_emr_template
                      data:
                        chief_complaint: cough and fever
                      publish: {}
                  - clinical_notes_template:
                      status: success
                      document_id: doc_def456
                      data:
                        assessment: Acute bronchitis
                      publish: {}
        '202':
          description: Session still processing — keep polling
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SessionProcessingResponse'
              example:
                session_id: ses_abc123def456
                status: processing
                created_at: '2026-06-06T14:21:07Z'
                expires_at: '2026-06-06T15:21:07Z'
                upload_url: https://api.eka.care/voice/v1/sessions/ses_abc123def456/audio
                audio_files_received: 4
                audio_files:
                  - 0.wav
                  - 1.wav
                  - 2.wav
                  - 3.wav
                additional_data:
                  _protocol:
                    version: '0.1'
                    upload_type: chunked
                    communication_protocol: http
                    requested_templates:
                      - eka_emr_template
                      - clinical_notes_template
                transcript: Patient presents with cough and fever...
        '206':
          description: Session completed with partial results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SessionPartialResponse'
        '404':
          description: Session not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '410':
          description: Session expired before processing was initiated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExpiredSessionResponse'
      security:
        - auth: []
components:
  schemas:
    SessionCompletedResponse:
      type: object
      description: Returned with HTTP 200 when the session completed successfully.
      properties:
        session_id:
          type: string
        upload_url:
          type: string
          description: >-
            Audio upload URL for the session (HTTPS for chunked, wss:// for
            stream).
        status:
          type: string
          example: completed
        created_at:
          type: string
          format: date-time
        completed_at:
          type: string
          format: date-time
          nullable: true
        model_used:
          type: string
          nullable: true
          example: pro
        language_detected:
          type: string
          nullable: true
          description: ISO 639-1 language code detected from the audio.
          example: en
        audio_files_received:
          type: integer
        audio_files:
          type: array
          items:
            type: string
        additional_data:
          type: object
          additionalProperties: true
        templates:
          type: array
          description: >
            Template results as a **list** — one entry per generated document,
            each a single-key object keyed by `template_id`. A template that
            produces multiple documents appears multiple times, so this is a
            list rather than a map. Each inner object carries `status`, `data`,
            `document_id`, `document_type`, `publish` metadata (and a
            `presigned_url` when applicable).
          items:
            type: object
            additionalProperties: true
          example:
            - eka_emr_template:
                status: success
                document_id: doc_abc123
                document_type: eka_emr_template
                data:
                  chief_complaint: cough and fever
                publish: {}
            - clinical_notes_template:
                status: success
                document_id: doc_def456
                data:
                  assessment: Acute bronchitis
                publish: {}
        transcript:
          type: string
          nullable: true
        patient_details:
          type: object
          additionalProperties: true
          nullable: true
    SessionProcessingResponse:
      type: object
      description: Returned with HTTP 202 while the session is still processing.
      properties:
        session_id:
          type: string
        upload_url:
          type: string
          description: >-
            Audio upload URL for the session (HTTPS for chunked, wss:// for
            stream).
        status:
          type: string
          example: processing
        created_at:
          type: string
          format: date-time
        expires_at:
          type: string
          format: date-time
        audio_files_received:
          type: integer
        audio_files:
          type: array
          items:
            type: string
        additional_data:
          type: object
          additionalProperties: true
        transcript:
          type: string
          nullable: true
          description: Partial or complete transcript if available.
        patient_details:
          type: object
          additionalProperties: true
          nullable: true
    SessionPartialResponse:
      type: object
      description: Returned with HTTP 206 when the session completed with partial results.
      properties:
        session_id:
          type: string
        upload_url:
          type: string
          description: >-
            Audio upload URL for the session (HTTPS for chunked, wss:// for
            stream).
        status:
          type: string
          example: partial
        created_at:
          type: string
          format: date-time
        completed_at:
          type: string
          format: date-time
          nullable: true
        model_used:
          type: string
          nullable: true
        language_detected:
          type: string
          nullable: true
        audio_files_received:
          type: integer
        audio_files_processed:
          type: integer
          description: Number of audio files successfully processed.
        audio_files:
          type: array
          items:
            type: string
        additional_data:
          type: object
          additionalProperties: true
        templates:
          type: array
          items:
            type: object
            additionalProperties: true
        transcript:
          type: string
          nullable: true
        processing_errors:
          type: array
          description: Non-fatal processing issues.
          items:
            type: object
            additionalProperties: true
        patient_details:
          type: object
          additionalProperties: true
          nullable: true
    ErrorResponse:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              description: Machine-readable error code.
              example: invalid_audio_format
            message:
              type: string
              description: Human-readable error message.
              example: Audio format 'audio/mp3' is not supported
            details:
              type: object
              additionalProperties: true
              description: Additional error context.
    ExpiredSessionResponse:
      type: object
      description: >-
        Returned with HTTP 410 when the session expired before processing
        started.
      properties:
        session_id:
          type: string
        upload_url:
          type: string
          description: >-
            Audio upload URL for the session (HTTPS for chunked, wss:// for
            stream).
        status:
          type: string
          example: expired
        created_at:
          type: string
          format: date-time
        expired_at:
          type: string
          format: date-time
        message:
          type: string
          example: Session expired before processing was initiated
        audio_files_received:
          type: integer
        audio_files:
          type: array
          items:
            type: string
        additional_data:
          type: object
          additionalProperties: true
        templates:
          type: object
          additionalProperties: true
        transcript:
          type: string
          nullable: true
  securitySchemes:
    auth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >-
        Bearer authentication header of the form `Bearer <token>`, where
        `<token>` is your auth token.

````