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

# Get a calendar

> Returns one connected calendar with the event types its provider currently offers, read live from the provider. This is the catalog you pick from when filling `scheduling.calendars`.

<Note>
  **Required scope:** `AGENTS_READ`
</Note>

## Behavior

Returns one connected calendar with `available_event_types`, the event types its provider currently offers. This is the catalog you pick from when filling `scheduling.calendars` on [Update configuration](/en/v2/api-reference/agent/update-agent).

The catalog is read live from the provider on every call, so it is always what the provider offers today.

## Reading available\_event\_types

`available_event_types` is absent for a provider that has no event-type concept. That is a different answer from an empty list, which means the provider offers none.

Two fields are worth knowing apart:

* `provider_description` is the blurb written in the calendar provider. It is context, not routing.
* `description`, which you send back in `scheduling.calendars`, is your own note on when the receptionist should book this event type rather than another. That is the text it matches a caller's reason against.

`required_questions` are answers the provider rejects a booking without, so the receptionist collects them during the call. They are read-only, and snapshotted when you select the event type.

## Errors

* `404 AGENT_CALENDAR_NOT_FOUND`: no calendar with that id is visible to you.
* `500 AGENT_CALENDAR_EVENT_TYPES_FETCH_FAILED`: the provider could not be reached. This one is retryable. If it keeps failing, the calendar connection has to be renewed in the Allo app.


## OpenAPI

````yaml GET /v2/api/calendars/{id}
openapi: 3.0.3
info:
  title: Allo API
  description: >-
    Allo API provides programmatic access to your Allo account, allowing you to
    manage webhooks, retrieve calls and contacts, and send SMS messages.


    All requests to `/v1/api/**` endpoints automatically go through quota
    checking and scope validation.
  version: 1.0.0
  contact:
    name: Allo Support
servers:
  - url: https://api.withallo.com
    description: Production server
security: []
tags:
  - name: Summary Templates
    description: >-
      Manage call summary templates that control how AI-generated call summaries
      are structured for your team.
  - name: Webhooks
    description: >-
      Manage webhook endpoints to receive real-time notifications about events
      in your Allo account. Each endpoint subscribes to one or more event topics
      and is verified with a signing secret.
  - name: Calls
    description: >-
      Retrieve and search call records with filtering and pagination. Filter
      calls by your Allo phone number.
  - name: Contacts
    description: >-
      Search and retrieve contact information with sorting and pagination.
      Includes engagement level tracking.
  - name: SMS
    description: Send SMS messages to phone numbers using your Allo numbers.
  - name: Phone Numbers
    description: Retrieve information about your Allo phone numbers.
  - name: Analytics
    description: Pre-computed call metrics, team performance, and outbound dial funnel
  - name: CRM
    description: Manage people, companies, and deals in your CRM.
  - name: Notes
    description: >-
      Internal team notes on conversations and CRM people, with @mention
      support. Notes are never visible to the contact.
  - name: Threads
    description: >-
      Team discussion threads attached to a conversation item (call, SMS, or
      conversation note). One thread per item.
  - name: AI Receptionist
    description: >-
      Read and write the AI receptionist configuration of a phone line: business
      details, voice, prompt, capabilities, business hours, transfer rules,
      scheduling calendars and knowledge sources.
paths:
  /v2/api/calendars/{id}:
    get:
      tags:
        - AI Receptionist
      summary: Get a connected calendar
      description: >-
        Returns one connected calendar with the event types its provider
        currently offers, read live from the provider. This is the catalog you
        pick from when filling `scheduling.calendars`.
      operationId: getCalendar
      parameters:
        - name: id
          in: path
          required: true
          description: Calendar identifier from `GET /v2/api/calendars`
          schema:
            type: string
            example: exc-abc123
      responses:
        '200':
          description: The calendar and its available event types
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/Calendar'
        '401':
          $ref: '#/components/responses/ApiUnauthorized'
        '403':
          $ref: '#/components/responses/ApiForbidden'
        '404':
          $ref: '#/components/responses/ApiNotFound'
        '429':
          $ref: '#/components/responses/ApiRateLimited'
      security:
        - ApiKeyAuth: []
components:
  schemas:
    Calendar:
      type: object
      description: >-
        A calendar connected to your workspace, whether or not a receptionist
        books on it.
      properties:
        id:
          type: string
          description: >-
            What `scheduling.calendars` on `PATCH
            /v2/api/numbers/{number}/agent` is keyed by.
          example: exc-abc123
        name:
          type: string
          nullable: true
          example: Acme bookings
        provider:
          type: string
          enum:
            - GOOGLE_CALENDAR
            - CAL_COM
            - CALENDLY
            - OUTLOOK
        status:
          type: string
          enum:
            - ACTIVE
            - DISCONNECTED
        is_team_default:
          type: boolean
        owner:
          $ref: '#/components/schemas/CalendarOwner'
          nullable: true
        available_event_types:
          type: array
          nullable: true
          description: >-
            Reported by `GET /v2/api/calendars/{id}` only, read live from the
            provider. Absent for a provider with no event-type concept, which is
            not the same answer as an empty list.
          items:
            $ref: '#/components/schemas/CalendarEventType'
    CalendarOwner:
      type: object
      description: The teammate who connected the calendar.
      properties:
        user_id:
          type: string
        user_name:
          type: string
          nullable: true
        email:
          type: string
          nullable: true
        is_current_user:
          type: boolean
    CalendarEventType:
      type: object
      description: >-
        An event type the provider currently offers on a calendar. This is the
        catalog you pick from when filling `scheduling.calendars`.
      properties:
        id:
          type: string
          example: '42'
        slug:
          type: string
          nullable: true
          example: intro-call
        title:
          type: string
          example: Intro call
        length_in_minutes:
          type: integer
          nullable: true
          example: 30
        provider_description:
          type: string
          nullable: true
          description: >-
            The blurb written in the calendar provider. Not the routing note the
            receptionist matches on: that one is the `description` you send in
            `scheduling.calendars`.
        required_questions:
          type: array
          nullable: true
          items:
            $ref: '#/components/schemas/SchedulingQuestion'
    ApiError:
      type: object
      properties:
        error:
          type: object
          properties:
            type:
              type: string
            code:
              type: string
            message:
              type: string
            retryable:
              type: boolean
            request_id:
              type: string
            retry_after_seconds:
              type: integer
              nullable: true
    SchedulingQuestion:
      type: object
      description: >-
        A question the calendar provider rejects a booking without, so the
        receptionist asks it during the call. Read-only: it is snapshotted when
        the event type is selected.
      properties:
        id:
          type: string
          example: notes
        label:
          type: string
          example: Anything we should know before the visit?
  responses:
    ApiUnauthorized:
      description: Invalid or missing API key
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
    ApiForbidden:
      description: API key lacks the required scope or access to the resource
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
    ApiNotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
    ApiRateLimited:
      description: Rate limit exceeded
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: Authorization

````