---
title: "Get Agenda"
method: GET
path: "/v0/inboxes/{inbox_id}/calendar/agenda"
tags: ["inboxes > calendar"]
---

# Get Agenda

`GET /v0/inboxes/{inbox_id}/calendar/agenda`

## Request

- Base URL: `https://api.agentmail.to`
- URL: `https://api.agentmail.to/v0/inboxes/{inbox_id}/calendar/agenda`
- Auth: HTTP bearer

Lists every date on the calendar in a time window, ordered by start time: one-off events,
and recurring events expanded into their individual dates, with cancelled dates left out.
Use it to answer "what is on the calendar".

The window defaults to now through 90 days from now and can be at most 366 days. Items omit
`description`, `metadata` and `attendees`; get an event by ID for the full object. An item
the inbox is invited to still carries `response_status`, so `needs_action` marks an
invitation waiting for a reply. Dates of
recurring events appear only up to about 90 days from now; use List Event Instances for a
recurring event's later dates. While a recurring event's dates are being regenerated after a
schedule change, which takes a few seconds, the agenda can briefly leave out some of them;
dates that have already started or ended stay as they ran.

The agenda is read in the region that serves the request, so it can trail a change made
moments earlier by a few seconds. Pass `consistency=primary` to read your own change right
away. Requires the `calendar_event_read` permission.

Calendar is available in US production (`api.agentmail.to`) but not yet in EU production
(`api.agentmail.eu`), which returns `403`.

## Path parameters

- `inbox_id` string, required: The ID of the inbox.

## Query parameters

- `consistency` 'eventual' | 'primary': Read consistency. `eventual` (default) reads from the region that serves your request and may lag a write made moments earlier by up to a few seconds. `primary` reads from the primary region and always reflects every completed write.
- `after` string, date-time: Start of the window, as a UTC timestamp ending in `Z` (an offset such as `-04:00` is rejected). Defaults to now. The window between `after` and `before` can be at most 366 days.
- `before` string, date-time: End of the window, as a UTC timestamp ending in `Z` (an offset such as `-04:00` is rejected). Defaults to 90 days after `after`. The window between `after` and `before` can be at most 366 days.
- `include_overlapping` boolean: When `true` (default), include events that started before `after` but are still running at `after`. When `false`, include only events that start inside the window.
- `limit` integer: Maximum number of events to return, from 1 to 100. Defaults to 50.
- `page_token` string: Page token for pagination.

## Response `200`

Response with status 200

- CalendarListCalendarEventsResponse
  - `count` integer, required: Number of items returned.
  - `limit` integer, required: Limit of number of items returned.
  - `next_page_token` string: Page token for pagination.
  - `events` CalendarCalendarEvent[], required: On List Events, ordered by `updated_at` descending. On Get Agenda and List Event Instances, ordered by `start_at` ascending.
    - `event_id` string, required: ID of a calendar event. A one-off or recurring event is addressed by its UUID. One date of a recurring event is addressed by a dated ID, `<uuid>_<slot>`: `<uuid>_t20261015T090000` for a timed date (the original wall-clock start in the event's time zone) or `<uuid>_d20261015` for an all-day date. Dated IDs are stable: moving a date keeps its original ID.
    - `kind` 'single' | 'series' | 'instance', required: What the event object represents. - `single`: a one-off event, addressed by its UUID. - `series`: the definition of a recurring event, addressed by its UUID. It carries `recurrence`; `start` and `end` describe its first date. - `instance`: one date of a recurring event, addressed by its dated ID. It carries `series_id`, `original_start` and `is_exception`.
    - `series_id` string: For `instance` events, the UUID of the series this date belongs to.
    - `original_start` string: A local wall-clock time without an offset, interpreted in the event's `timezone`. Timed events use `YYYY-MM-DDTHH:mm:ss` (for example `2026-10-15T09:00:00`). All-day events use `YYYY-MM-DD`. Years must be between 1900 and 9999.
    - `original_start_at` string, date-time: For `instance` events, `original_start` as a UTC instant.
    - `is_exception` boolean: For `instance` events, `true` when this date was edited or moved, individually or by a `mode=future` change.
    - `title` string, required: Title of the event.
    - `description` string: Description of the event. Omitted from agenda and instance list items.
    - `location` string: Location of the event.
    - `metadata` unknown
    - `status` 'confirmed' | 'tentative' | 'cancelled', required: Status of the event. A `cancelled` event or date stays readable but sends no `calendar.event.starting` or `calendar.event.ending` webhooks (cancelling a date that is already running still sends its `calendar.event.ending`). A date cancelled by deleting its dated ID is removed from the series instead, so reading it can return `404` or `410`.
    - `all_day` boolean, required: Whether this is an all-day event.
    - `start` string, required: A local wall-clock time without an offset, interpreted in the event's `timezone`. Timed events use `YYYY-MM-DDTHH:mm:ss` (for example `2026-10-15T09:00:00`). All-day events use `YYYY-MM-DD`. Years must be between 1900 and 9999.
    - `end` string, required: A local wall-clock time without an offset, interpreted in the event's `timezone`. Timed events use `YYYY-MM-DDTHH:mm:ss` (for example `2026-10-15T09:00:00`). All-day events use `YYYY-MM-DD`. Years must be between 1900 and 9999.
    - `timezone` string, required: IANA time zone name, for example `America/New_York`, `Europe/London` or `UTC`. Requests accept any capitalization and IANA aliases such as `US/Eastern`. The calendar stores and returns the canonical name, which for some zones is an older spelling: `Asia/Kolkata` is returned as `Asia/Calcutta`. Abbreviations such as `PST` and Windows names such as `Pacific Standard Time` are rejected.
    - `duration_mode` 'nominal' | 'exact', required: How the event's length is kept when a date crosses a daylight-saving change. - `exact`: the event lasts the same elapsed time. Default for one-off timed events. - `nominal`: the event keeps its wall-clock end time (a 09:00 to 10:00 meeting stays 09:00 to 10:00 local time). Default for recurring timed events. All-day events are always `nominal`.
    - `duration_value` integer, required: Length of the event, in milliseconds for timed events and in days for all-day events.
    - `start_at` string, date-time, required: Start as a UTC instant. This is when `calendar.event.starting` is due.
    - `end_at` string, date-time, required: End as a UTC instant. This is when `calendar.event.ending` is due.
    - `recurrence` CalendarRecurrence: The recurrence of a series, as stored.
      - `rule` string, required: Normalized RRULE body, without the `RRULE:` prefix.
      - `exdates` CalendarWallTime[]
      - `rdates` CalendarRecurrenceDate[]
        - union: A wall-clock date or date-time, or (timed events only) a period.
          - string: A local wall-clock time without an offset, interpreted in the event's `timezone`. Timed events use `YYYY-MM-DDTHH:mm:ss` (for example `2026-10-15T09:00:00`). All-day events use `YYYY-MM-DD`. Years must be between 1900 and 9999.
          - CalendarRecurrencePeriod: An extra date (RDATE) given as a period. Specify exactly one of `end` or `duration`.
            - `start` string, required: A local wall-clock time without an offset, interpreted in the event's `timezone`. Timed events use `YYYY-MM-DDTHH:mm:ss` (for example `2026-10-15T09:00:00`). All-day events use `YYYY-MM-DD`. Years must be between 1900 and 9999.
            - `end` string: A local wall-clock time without an offset, interpreted in the event's `timezone`. Timed events use `YYYY-MM-DDTHH:mm:ss` (for example `2026-10-15T09:00:00`). All-day events use `YYYY-MM-DD`. Years must be between 1900 and 9999.
            - `duration` string: ISO 8601 duration, for example `PT30M`.
      - `truncate_before` string: A local wall-clock time without an offset, interpreted in the event's `timezone`. Timed events use `YYYY-MM-DDTHH:mm:ss` (for example `2026-10-15T09:00:00`). All-day events use `YYYY-MM-DD`. Years must be between 1900 and 9999.
    - `attendees` CalendarAttendee[]: Attendees of the event. Omitted from agenda and instance list items; `attendee_count` is always present.
      - `email` string, required: Email address of the attendee. Stored in lowercase. Must be unique within the event.
      - `name` string: Display name of the attendee. At most 256 characters.
      - `status` 'needs_action' | 'accepted' | 'declined' | 'tentative': The attendee's response to the invitation.
      - `role` 'required' | 'optional': Whether the attendee's presence is required.
      - `comment` string: Comment the attendee sent with their response. At most 4,096 UTF-8 bytes; on create or update, a longer comment is dropped rather than rejected.
      - `responded_at` string, date-time: Time at which the attendee last responded.
    - `attendee_count` integer, required: Number of attendees.
    - `response_status` 'needs_action' | 'accepted' | 'declined' | 'tentative': The attendee's response to the invitation.
    - `uid` string, required: iCalendar UID of the event. Invitations about this event carry the same UID.
    - `sequence` integer, required: iCalendar SEQUENCE number. It increases when a change to a one-off or series event affects what attendees see (time, status, title, description, location, recurrence or attendees). A change to a dated event increases it only when the change is sent with `send_invites`.
    - `source` 'api' | 'email', required: Where the event came from. `api` events were created through this API and the inbox is their organizer. `email` events were created from a calendar invitation (iMIP) received by the inbox; their organizer is the sender of the invitation.
    - `organizer_email` string: Email address of the organizer. For `api` events, the inbox.
    - `origin_message_id` string: For `email` events, the ID of the message whose invitation last created or updated the event.
    - `resource_revision` integer: Revision of the resource. It increases on every change. The resource's `etag` is `"rv-<resource_revision>"`.
    - `created_at` string, date-time, required: Time at which the event (or, for a date, the definition governing it) was created.
    - `updated_at` string, date-time, required: Time at which the event (or, for a date, the definition governing it) was last updated.
    - `etag` string: The event's or date's current version, also sent as the `ETag` response header. Send it in `If-Match` to make an update, delete or response conditional. Present on Get, Create, Update, Delete and Respond responses; list items and webhooks omit it. Treat it as opaque: a dated event's `etag` (`"occ-..."`) is not derived from `resource_revision`.

## Other responses

- `400`: Error response with status 400
- `403`: Calendar isn't available in this region (EU production), or the API key lacks the required calendar permission.
- `404`: Error response with status 404

## Changes

- **2026-10-16** `3f5c7830c952`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/agentmail-to/apis/api/changes/v0/inboxes/:inbox_id/calendar/agenda/get.md)

---

[API](https://skmtc.dev/agentmail-to/apis/api.md) - [All operations](https://skmtc.dev/agentmail-to/apis/api/llms.txt) - [OpenAPI document](https://skmtc.dev/agentmail-to/apis/api/revisions/a9792efe7bdf?raw)