GET
/
api
/
v1
/
calendar
/
events
{
  "count": 123,
  "page": 123,
  "limit": 123,
  "pages": 123,
  "events": [
    {
      "id": 123,
      "uuid": "<string>",
      "title": "<string>",
      "event_type": "<string>",
      "status": "<string>",
      "start_time": "<string>",
      "end_time": "<string>",
      "duration_minutes": 123,
      "location": "<string>",
      "has_video_conference": true,
      "video_conference_url": "<string>",
      "created_by_ai_agent": true,
      "ai_agent": {
        "id": 123,
        "name": "<string>",
        "assistant_id": "<string>"
      },
      "customer": {
        "name": "<string>",
        "email": "<string>",
        "phone": "<string>"
      }
    }
  ],
  "error": "<string>",
  "message": "<string>"
}

Get a paginated list of calendar events with various filtering options.

​
Query Parameters

​
start_date
string

Start date for the range. If not provided, defaults to the current date.

​
end_date
string

End date for the range. If not provided, defaults to 30 days from the start date.

​
status
string

Filter by event status. Valid values: scheduled, confirmed, cancelled, completed, no_show.

​
page
integer
default:1

Page number for pagination.

​
limit
integer
default:10

Number of results per page.

​
Response

​
count
integer

Total number of events matching the criteria.

​
page
integer

Current page.

​
limit
integer

Results per page.

​
pages
integer

Total number of pages.

​
events
array

List of events.

​
Example Request

curl -X GET 'https://api.klen.ai/api/v1/calendar/events?start_date=2025-05-01&end_date=2025-05-31&status=confirmed&page=1&limit=10' \
  -H 'Authorization: Bearer klen_YOUR_API_KEY'

​
Example Response

{
  "count": 25,
  "page": 1,
  "limit": 10,
  "pages": 3,
  "events": [
    {
      "id": 123,
      "uuid": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
      "title": "Client Meeting",
      "event_type": "meeting",
      "status": "confirmed",
      "start_time": "2025-05-01T14:00:00.000Z",
      "end_time": "2025-05-01T15:00:00.000Z",
      "duration_minutes": 60,
      "location": "Conference Room A",
      "has_video_conference": true,
      "video_conference_url": "https://meet.google.com/abc-defg-hij",
      "created_by_ai_agent": true,
      "ai_agent": {
        "id": 42,
        "name": "Meeting Scheduler",
        "assistant_id": "asst_01234567890"
      },
      "customer": {
        "name": "John Smith",
        "email": "[email protected]",
        "phone": "+15551234567"
      }
    },
    {
      "id": 124,
      "uuid": "63f5f61f-4271-4870-bc31-cbd75856663b",
      "title": "Project Review",
      "event_type": "video_call",
      "status": "confirmed",
      "start_time": "2025-05-02T10:00:00.000Z",
      "end_time": "2025-05-02T11:30:00.000Z",
      "duration_minutes": 90,
      "location": null,
      "has_video_conference": true,
      "video_conference_url": "https://zoom.us/j/123456789",
      "created_by_ai_agent": false,
      "customer": {
        "name": "Jane Doe",
        "email": "[email protected]",
        "phone": "+15557654321"
      }
    }
    // ... more events
  ]
}

​
Error Responses

​
error
string

Error code.

​
message
string

Error message.

​
Invalid Parameters (400)

{
  "error": "invalid_parameter",
  "message": "Invalid date format. Expected YYYY-MM-DD"
}

​
Unauthorized (401)

{
  "error": "authentication_required",
  "message": "API key is required"
}

​
Permission Denied (403)

{
  "error": "permission_denied",
  "message": "This API key does not have can_read_calendar permission"
}

​
Server Error (500)

{
  "error": "server_error",
  "message": "An unexpected server error occurred"
}