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

# List calendar events

> Fetch Pharen Hub calendar events for sync jobs, dashboards, and reporting tools, with filters for date range, team UUID, and source calendar.

Returns calendar events for the authenticated key. Use this endpoint for sync jobs, dashboards, and reporting tools that need read-only calendar data.

<Note>
  Required API key scope: `calendar:read`.
</Note>

## Query parameters

<ParamField query="range_start" type="string">
  ISO 8601 datetime for the beginning of the event window. If omitted, Pharen uses a bounded default range.
</ParamField>

<ParamField query="range_end" type="string">
  ISO 8601 datetime for the end of the event window. Must be after `range_start`.
</ParamField>

<ParamField query="team_id" type="string">
  Team UUID for team-scoped keys. Workspace-wide keys can omit this unless the integration is intentionally targeting one team.
</ParamField>

## Response

<ResponseField name="id" type="string">
  Event UUID.
</ResponseField>

<ResponseField name="calendar_id" type="string">
  UUID of the calendar that owns the event.
</ResponseField>

<ResponseField name="title" type="string">
  Event title.
</ResponseField>

<ResponseField name="starts_at" type="string">
  Event start time as an ISO 8601 datetime.
</ResponseField>

<ResponseField name="ends_at" type="string">
  Event end time as an ISO 8601 datetime.
</ResponseField>

<ResponseField name="is_all_day" type="boolean">
  Whether the event spans the full day.
</ResponseField>

<ResponseField name="location" type="string">
  Event location, if set.
</ResponseField>

<ResponseField name="conference_url" type="string">
  Meeting or conference URL, if set.
</ResponseField>

<ResponseField name="attendees" type="array">
  Attendee objects associated with the event.
</ResponseField>


## OpenAPI

````yaml openapi.json GET /api/calendar/events/
openapi: 3.1.0
info:
  title: Pharen Hub API
  version: 1.0.0
  description: >-
    Scoped REST API for Pharen Hub workspaces, calendars, lists, docs,
    workflows, and agents.
servers:
  - url: '{baseUrl}'
    description: Pharen Hub API base URL
    variables:
      baseUrl:
        default: https://pharen.app
        description: >-
          The Pharen Hub API origin. Keep the default for production, or enter
          another environment such as http://localhost:8000.
security:
  - bearerAuth: []
tags:
  - name: Calendar
    description: Calendar source and event operations.
  - name: Lists
    description: Saved list data and metadata operations.
  - name: Docs
    description: Document and collection operations.
  - name: Workflows
    description: Workflow definition and execution operations.
  - name: Agents
    description: Agent catalog and chat operations.
paths:
  /api/calendar/events/:
    get:
      tags:
        - Calendar
      summary: List calendar events
      description: >-
        Fetch calendar events for sync jobs, dashboards, and reporting tools.
        Requires the `calendar:read` scope.
      operationId: listCalendarEvents
      parameters:
        - name: range_start
          in: query
          description: ISO 8601 datetime for the beginning of the event window.
          schema:
            type: string
            format: date-time
            example: '2026-07-01T00:00:00Z'
        - name: range_end
          in: query
          description: >-
            ISO 8601 datetime for the end of the event window. Must be after
            `range_start`.
          schema:
            type: string
            format: date-time
            example: '2026-07-31T23:59:59Z'
        - name: team_id
          in: query
          description: Team UUID for team-scoped keys.
          schema:
            type: string
            format: uuid
            example: 1f5e2d4c-7a5b-45db-b61a-b7d42f3f94cc
      responses:
        '200':
          description: Calendar events returned.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/CalendarEvent'
                  total:
                    type: integer
                    example: 12
                  page:
                    type: integer
                    example: 1
                  per_page:
                    type: integer
                    example: 20
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
components:
  schemas:
    CalendarEvent:
      type: object
      properties:
        id:
          type: string
          format: uuid
        calendar_id:
          type: string
          format: uuid
        title:
          type: string
          example: Quarterly planning
        starts_at:
          type: string
          format: date-time
        ends_at:
          type: string
          format: date-time
        is_all_day:
          type: boolean
        location:
          type: string
        conference_url:
          type: string
          format: uri
        attendees:
          type: array
          items:
            $ref: '#/components/schemas/EventAttendee'
    EventAttendee:
      type: object
      properties:
        email:
          type: string
          format: email
        name:
          type: string
        status:
          type: string
          enum:
            - needs_action
            - accepted
            - declined
            - tentative
    ErrorResponse:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              example: forbidden
            message:
              type: string
              example: This API key does not have the required scope.
            details:
              type: object
              additionalProperties: true
  responses:
    Unauthorized:
      description: The request did not include a valid API key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Forbidden:
      description: >-
        The API key is valid but does not have the required scope or workspace
        access.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Paste your Pharen API key without the Bearer prefix.
      x-default: phk_your_api_key

````