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

# List a calendar's events

> Events on one calendar in a time window, earliest first, optionally only
those whose title contains `q` (case-insensitive). Recurring events are
returned as individual occurrences with `VIRT/<seriesId>/<occurrenceId>`
ids. A private event on a calendar shared without private access comes
back as a "Busy (private)" block with `private: true` and no details.
The acting user must be able to read the calendar.




## OpenAPI

````yaml /openapi.yaml get /api/calendars/{calendarId}/events
openapi: 3.0.3
info:
  title: Aptly API
  version: '1.1'
  description: |
    The Aptly API lets external systems work with boards, contacts, inboxes,
    tasks, files, and other Aptly resources.

    Most endpoints accept an API key in the `x-token` header. Some endpoints
    also accept a delegate token or partner bearer token, as shown in each
    operation's security requirements, and explicitly public endpoints require
    no credential. API keys are scoped to a company and may be restricted to
    specific boards and read, insert, or update permissions; requests outside
    those restrictions receive a 403 `FORBIDDEN` response.
servers:
  - url: https://core-api.getaptly.com
    description: Production
security:
  - ApiKeyHeader: []
paths:
  /api/calendars/{calendarId}/events:
    get:
      tags:
        - Calendars
      summary: List a calendar's events
      description: |
        Events on one calendar in a time window, earliest first, optionally only
        those whose title contains `q` (case-insensitive). Recurring events are
        returned as individual occurrences with `VIRT/<seriesId>/<occurrenceId>`
        ids. A private event on a calendar shared without private access comes
        back as a "Busy (private)" block with `private: true` and no details.
        The acting user must be able to read the calendar.
      operationId: listCalendarEvents
      parameters:
        - name: calendarId
          in: path
          required: true
          schema:
            type: string
          description: Calendar id from `GET /api/calendars`.
        - name: q
          in: query
          required: false
          schema:
            type: string
            minLength: 1
            maxLength: 200
          description: Only events whose title contains this text (case-insensitive).
        - name: from
          in: query
          required: false
          schema:
            type: string
            format: date-time
          description: Window start. Default now.
        - name: to
          in: query
          required: false
          schema:
            type: string
            format: date-time
          description: >-
            Window end. Default `from` + 7 days. Windows longer than 180 days
            are capped (see `range`).
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 50
            default: 20
          description: >-
            Max events returned, earliest first. No paging; narrow the window
            for more.
        - name: userId
          in: query
          required: false
          schema:
            type: string
          description: >-
            Acting user. Required with an API key or partner token; a delegate
            token is its own user.
      responses:
        '200':
          description: Events in the window.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/CalendarEvent'
                  range:
                    type: object
                    description: >-
                      The window actually searched (after defaults and the
                      180-day cap).
                    properties:
                      from:
                        type: string
                        format: date-time
                      to:
                        type: string
                        format: date-time
        '400':
          description: Invalid query, an empty window, or missing `userId`.
        '401':
          description: The acting user is not in the company.
        '403':
          description: API key without read permission.
        '404':
          description: Calendar not found, or the acting user cannot read it.
      security:
        - ApiKeyHeader: []
        - DelegateToken: []
        - PartnerBearer: []
components:
  schemas:
    CalendarEvent:
      type: object
      properties:
        _id:
          type: string
          description: >-
            Event id. A recurring occurrence is
            `VIRT/<seriesId>/<occurrenceId>`.
        title:
          type: string
        start:
          type: string
          format: date-time
        end:
          type: string
          format: date-time
        allDay:
          type: boolean
        calendar:
          type: string
          description: Calendar name.
        calendarId:
          type: string
        timezone:
          type: string
        recurring:
          type: boolean
        seriesId:
          type: string
          description: The series id, on a recurring occurrence.
        private:
          type: boolean
          description: >-
            Present (true) when the event is redacted to a busy block; no
            details below are returned then.
        description:
          type: string
        location:
          type: string
        recurrence:
          type: string
          description: Human-readable repeat rule.
        references:
          type: array
          items:
            type: object
        relatedStreamIds:
          type: array
          items:
            type: string
        attendees:
          type: array
          items:
            type: object
            properties:
              name:
                type: string
              email:
                type: string
              response:
                type: string
        showingStatus:
          type: string
  securitySchemes:
    ApiKeyHeader:
      type: apiKey
      in: header
      name: x-token
    DelegateToken:
      type: apiKey
      in: header
      name: Authorization
      description: 'Delegate token issued by the platform. Format: `DelegateToken <token>`'
    PartnerBearer:
      type: http
      scheme: bearer
      description: 'Partner token. Format: `Authorization: Bearer <token>`'

````

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