Skip to main content
GET
/
calendar
/
events
List Calendar Events
curl --request GET \
  --url https://api.meestream.ai/api/v1/calendar/events \
  --header 'Authorization: <api-key>'
{
  "results": [
    {
      "id": "<string>",
      "start_time": "2023-11-07T05:31:56Z",
      "end_time": "2023-11-07T05:31:56Z",
      "calendar_id": "<string>",
      "platform": "<string>",
      "platform_id": "<string>",
      "ical_uid": "<string>",
      "meeting_platform": "<string>",
      "meeting_url": "<string>",
      "created_at": "2023-11-07T05:31:56Z",
      "updated_at": "2023-11-07T05:31:56Z",
      "is_deleted": true,
      "bots": "<array>",
      "raw": {}
    }
  ],
  "has_more": true,
  "next": "<string>",
  "previous": "<string>"
}

​
Overview

Lists calendar events with meeting links. Supports pagination, time filtering, and incremental sync with Google Calendar. Only returns events that have meeting links (Zoom, Meet, Teams, etc.).

​
Request

Endpoint: GET /calendar/events or GET /calendar/events/list Headers: 
Authorization: Token <api_key>
Query Parameters:
ParameterTypeDefaultDescription
time_minISO 8601Now - 1 dayStart of time range for filtering events
time_maxISO 8601Now + 28 daysEnd of time range for filtering events
calendar_idstringAll calendarsFilter by specific calendar ID
syncbooleanfalseForce sync from Google Calendar
cleanup_duplicatesbooleanfalseClean up duplicate events
limitinteger50Number of events per page (1-100)
cursorstringnullPagination cursor for next page

​
Response

​
Success Response (200)

{
  "next": "base64_encoded_cursor_or_null",
  "previous": "base64_encoded_cursor_or_null",
  "results": [
    {
      "id": "evt_abc123",
      "start_time": "2024-12-20T10:00:00+00:00",
      "end_time": "2024-12-20T11:00:00+00:00",
      "calendar_id": "primary",
      "platform": "google_calendar",
      "platform_id": "google_event_id",
      "ical_uid": "[email protected]",
      "meeting_platform": "google_meet",
      "meeting_url": "https://meet.google.com/abc-defg-hij",
      "created_at": "2024-12-18T10:00:00Z",
      "updated_at": "2024-12-18T10:00:00Z",
      "is_deleted": false,
      "bots": [
        {
          "id": "bot_uuid",
          "status": "Scheduled",
          "scheduled_join_time": "2024-12-20T09:57:00+00:00",
          "bot_username": "MeetStream Bot",
          "platform": "google_meet",
          "meeting_link": "https://meet.google.com/abc-defg-hij",
          "is_scheduled": true
        }
      ],
      "raw": {
        "summary": "Team Meeting",
        "description": "...",
        "location": "..."
      }
    }
  ],
  "has_more": true
}

​
Response Fields

FieldTypeDescription
nextstring | nullBase64-encoded cursor for the next page, or null if no more pages
previousstring | nullBase64-encoded cursor for the previous page, or null if no previous page
resultsarrayList of calendar events
results[].idstringEvent ID
results[].start_timeISO 8601Event start time
results[].end_timeISO 8601Event end time
results[].calendar_idstringCalendar ID this event belongs to
results[].platformstringCalendar platform (e.g., “google_calendar”)
results[].platform_idstringOriginal platform event ID
results[].ical_uidstringiCal UID for the event
results[].meeting_platformstringDetected meeting platform (google_meet, zoom, microsoft_teams, etc.)
results[].meeting_urlstringMeeting link URL
results[].created_atISO 8601When the event was created in the system
results[].updated_atISO 8601When the event was last updated
results[].is_deletedbooleanWhether the event has been deleted
results[].botsarrayList of bots scheduled for this event
results[].bots[].idstringBot ID
results[].bots[].statusstringBot status (e.g., “Scheduled”, “InMeeting”)
results[].bots[].scheduled_join_timeISO 8601When the bot is scheduled to join
results[].bots[].bot_usernamestringBot display name
results[].bots[].platformstringMeeting platform
results[].bots[].meeting_linkstringMeeting link
results[].bots[].is_scheduledbooleanWhether the bot is scheduled
results[].rawobjectOriginal calendar event data from Google Calendar
has_morebooleanWhether there are more results available

​
Error Responses

​
400 Bad Request

Invalid time format or invalid query parameters.

​
401 Unauthorized

Missing user_id in token or invalid authentication.

​
404 Not Found

User not found or calendar not connected.

​
500 Internal Server Error

An error occurred while fetching events.

​
Features

  • Meeting Link Filtering: Only returns events with meeting links (Zoom, Meet, Teams, etc.)
  • Incremental Sync: Supports incremental sync using Google Calendar sync tokens
  • Recurring Events: Automatically expands recurring events into individual occurrences
  • Linked Bot Schedules: Includes linked bot schedules for each event
  • Pagination: Supports cursor-based pagination for large result sets

​
Pagination

Use the cursor parameter to paginate through results:
  1. First request: Don’t include cursor parameter
  2. Next page: Use the next value from the previous response as the cursor parameter
  3. Previous page: Use the previous value as the cursor parameter

​
Meeting Platform Detection

The system automatically detects meeting platforms from:
  1. hangoutLink field (Google Meet)
  2. conferenceData.entryPoints (video conference data)
  3. location field (meeting URLs)
  4. description field (meeting URLs)
Supported platforms:
  • Google Meet (meet.google.com)
  • Zoom (zoom.us)
  • Microsoft Teams (teams.microsoft.com)
  • Webex, GoToMeeting, BlueJeans, Whereby (for detection)

​
Recurring Events

Recurring events are automatically expanded into individual occurrences:
  • Master Events: Have a RecurrenceRule (RRULE) and are marked with IsRecurring: true
  • Occurrences: Expanded from master events, marked with IsExpanded: "true" and MasterEventID

Authorizations

​
Authorization
string
header
required

All API endpoints are authenticated using API Keys. The key should be included in the 'Authorization' header, prefixed with 'Token '. Example: 'Authorization: Token YOUR_API_KEY'.

Query Parameters

​
time_min
string<date-time>

Start of time range for filtering events (ISO 8601)

​
time_max
string<date-time>

End of time range for filtering events (ISO 8601)

​
calendar_id
string

Filter by specific calendar ID

​
sync
boolean
default:false

Force sync from Google Calendar

​
cleanup_duplicates
boolean
default:false

Clean up duplicate events

​
limit
integer
default:50

Number of events per page (1-100)

Required range: 1 <= x <= 100
​
cursor
string

Pagination cursor for next page

Response

Returns the list of calendar events.

​
results
object[]
required

List of calendar events

​
has_more
boolean
required

Whether there are more results available

​
next
string | null

Base64-encoded cursor for the next page, or null if no more pages

​
previous
string | null

Base64-encoded cursor for the previous page, or null if no previous page