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

# Get a receptionist task

> One AI Receptionist inbox task. Returns 404 if the task isn't your organization's. Requires the receptionist:read scope.

| Requirement | Detail |
| - | - |
| **Scope** | `receptionist:read` |
| **Rate limit** | About 60 requests per minute per API key (shared by all endpoints; approximate) |
| **Cost** | Free |

> [!TIP]
>
> **Safety**
>
> * **Writes data:** No
> * **Safe to retry:** Yes
> * **Contacts an outside system:** None
> * **Dry run:** Not needed (read-only).

> [!NOTE]
>
> Rolling out: this endpoint is on staging first and not yet on `api.healos.ai`.

One inbox task, with the same fields the list returns. Another organization's task is a `404`.

Guide: [Calls and inbox](https://docs.healos.ai/guides/receptionist/calls-and-inbox.md). Errors: [Error catalog](https://docs.healos.ai/errors.md).


## OpenAPI

````yaml openapi/ext-api-v1.json GET /receptionist/tasks/{taskId}
openapi: 3.0.0
info:
  title: Healos External API
  version: 1.0.0
  description: >-
    External API for managing patients, documents, and appointments, listing
    providers and note templates, pulling clinical notes (with transcript and
    patient context), running insurance eligibility checks, browsing the EHR
    action catalog, reading AI Receptionist calls (summary, transcript,
    extracted details and recording), managing the AI Receptionist inbox tasks,
    and registering webhooks for note and document events.
servers:
  - url: https://api.healos.ai/ext-api/v1
    description: Production
  - url: http://localhost:8787/ext-api/v1
    description: Local development
security:
  - ApiKeyAuth: []
paths:
  /receptionist/tasks/{taskId}:
    get:
      tags:
        - Receptionist
      summary: Get a receptionist task
      description: >-
        One AI Receptionist inbox task. Returns 404 if the task isn't your
        organization's. Requires the receptionist:read scope.
      parameters:
        - schema:
            type: string
            description: Task identifier, from GET /receptionist/tasks.
            example: 7a5c0000-0000-4000-8000-000000000001
          required: true
          name: taskId
          in: path
      responses:
        '200':
          description: The task
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReceptionistTaskResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Insufficient scope (needs receptionist:read)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Task not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RateLimitError'
components:
  schemas:
    ReceptionistTaskResponse:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/ReceptionistTask'
      required:
        - data
    Error:
      type: object
      properties:
        error:
          type: string
      required:
        - error
    RateLimitError:
      type: object
      properties:
        error:
          type: string
          example: Rate limit exceeded. Please retry after the window resets.
        code:
          type: string
          enum:
            - daily_cap_reached
          description: >-
            Set when the organization reached its daily cap for this paid
            operation (not on a per-minute limit).
        reset_at:
          type: string
          format: date-time
          description: 'With `code`: when the daily cap resets (next 00:00 UTC).'
          example: '2026-10-28T00:00:00.000Z'
      required:
        - error
    ReceptionistTask:
      type: object
      properties:
        id:
          type: string
          example: 7a5c0000-0000-4000-8000-000000000001
        title:
          type: string
        category:
          type: string
          nullable: true
        status:
          type: string
          example: todo
        source:
          type: string
          description: >-
            `manual` (created by staff or the API), `call` (created from a call)
            or `system`.
          example: call
        notes:
          type: string
          nullable: true
        due_date:
          type: string
          nullable: true
          example: '2026-10-30'
        patient_id:
          type: string
          nullable: true
        patient_label:
          type: string
          nullable: true
        assigned_provider_calendar_id:
          type: string
          nullable: true
        linked_call_id:
          type: string
          nullable: true
        caller_phone:
          type: string
          nullable: true
          description: >-
            The number the linked call came from, for a call back. Null without
            a phone call.
          example: '+15555550100'
        ehr_source:
          type: string
          nullable: true
          description: The EHR the organization had connected when the task was created.
        created_at:
          type: string
          example: '2026-10-27T14:07:50.000Z'
        updated_at:
          type: string
          example: '2026-10-27T14:08:02.000Z'
      required:
        - id
        - title
        - category
        - status
        - source
        - notes
        - due_date
        - patient_id
        - patient_label
        - assigned_provider_calendar_id
        - linked_call_id
        - caller_phone
        - ehr_source
        - created_at
        - updated_at
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: API key obtained from /api/v1/ext-api-keys

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.