List events

GEThttps://<your-url>/api/v2/events

MCP id events.indexAlso on this path: POST Create an event

Returns agenda events, latest start first.

Token scope: api:read:events
Without it: 403 insufficient-token-scope.
Permission: events::manage_self
Without it: 403 insufficient-permission.
Rate cost: 1 unit, read bucket. view=detail makes it 3. Adds: with_total=1 +2, each include +1, q +2.
Also: If-None-Match answers 304 when nothing changed. Never cached: private, no-store. Unknown query parameters are refused, never ignored.

Both are checked, scope first. A token never does more than its user. How access is checked

Request

Example: One week of my agenda

curl -G \
  'https://<your-url>/api/v2/events' \
  --data-urlencode 'filter[start][gte]=2026-03-02T00:00:00Z' \
  --data-urlencode 'filter[start][lte]=2026-03-08T23:59:59Z' \
  --data-urlencode 'sort=start' \
  -H 'Authorization: Bearer <token>' \
  -H 'Accept: application/json'

const response = await fetch('https://<your-url>/api/v2/events?filter[start][gte]=2026-03-02T00%3A00%3A00Z&filter[start][lte]=2026-03-08T23%3A59%3A59Z&sort=start', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer <token>',
    'Accept': 'application/json',
  },
});

use Illuminate\Support\Facades\Http;

$response = Http::withToken('<token>')
    ->acceptJson()
    ->get('https://<your-url>/api/v2/events?filter[start][gte]=2026-03-02T00%3A00%3A00Z&filter[start][lte]=2026-03-08T23%3A59%3A59Z&sort=start');

import requests
response = requests.request(
    'GET',
    'https://<your-url>/api/v2/events?filter[start][gte]=2026-03-02T00%3A00%3A00Z&filter[start][lte]=2026-03-08T23%3A59%3A59Z&sort=start',
    headers={'Authorization': 'Bearer <token>', 'Accept': 'application/json'},
)

Response

The shape of the response, with sample values.

{
  "data": [
    {
      "id": 1,
      "user_id": 1,
      "task_id": 1,
      "parent_event_id": 1,
      "occurrence_date": "2026-03-04",
      "start": "2026-03-03T09:00:00Z",
      "end": "2026-03-03T10:30:00Z",
      "title": "Design review",
      "is_all_day": false,
      "is_recurring": false,
      "recurrence_interval": 1,
      "recurrence_frequency": "day"
    }
  ],
  "meta": {
    "page": {
      "per_page": 1,
      "next_cursor": "…",
      "prev_cursor": "…",
      "total": 1
    }
  },
  "links": {
    "self": "https://<your-url>/api/v2/work-items/1",
    "next": "https://<your-url>/api/v2/work-items/1",
    "prev": "https://<your-url>/api/v2/work-items/1"
  }
}

8 more fields, listed under Response

A caller sees only their own events unless they hold events::manage_for_others, and filter[user_id] defaults to the calling user even then; pass filter[user_id]=me,<id> to widen it, which requires that permission. Fetch one window of the calendar with filter[start][gte] and filter[start][lte]. A recurring master is one row: its occurrences are generated from recurrence_frequency, recurrence_interval, selected_weekdays and recurrence_exceptions and are not returned individually, except where plnnrly has separated one into a row of its own (those rows carry parent_event_id). meta.page.total is only computed when you ask for it with with_total=true. Deleted events are excluded unless you pass trashed=with or trashed=only.

Query parameters

Unknown parameters are refused with 400, naming the parameter.

48 parameters in 7 groups

Views

viewstring

Which field set to render.

summarydefaultdetail

Pagination

Cursor pagination only. Follow links.next.

per_pageinteger1 to 100

Rows per page. At most 25 when include names a to-many relation; a larger value is 400 invalid-query-parameter.

Default: 25

cursorstring

Opaque keyset cursor from a previous page's links.next. Never construct one by hand.

with_totalboolean

Whether meta.page.total is counted for this request.

Default: false

Filters

=: equals
[in]: any of a comma-separated list
[null]: true or false: whether it is empty
[gte][lte][lt]: at least, at most, less than
[ne]: not equal

filter[created_at]timestamp (YYYY-MM-DDThh:mm:ssZ)=[gte][lt]

Creation timestamp. Pair with sort=id for a stable full export.

filter[end]timestamp (YYYY-MM-DDThh:mm:ssZ)=[gte][lte]

When the event ends.

filter[is_all_day]boolean

Whether the event occupies whole days rather than a time range.

filter[is_recurring]boolean

Whether the event is the master of a recurring series.

filter[occurrence_date]date (YYYY-MM-DD)=[gte][lte][null]

The series date a separated occurrence replaces.

Whether the field is null.

filter[parent_event_id]integer=[in][null]

Master event of a separated occurrence. null selects everything that is not a separated occurrence.

A comma-separated list of at most 100 values.

filter[recurrence_end]timestamp (YYYY-MM-DDThh:mm:ssZ)=[gte][lte][null]

Last moment a series may generate an occurrence. null selects the open-ended series.

Whether the field is null.

filter[recurrence_frequency]string=[ne][in]

The unit a recurring series repeats in.

A comma-separated list of at most 100 values.

dayweekmonthyear

New values may be added.

filter[recurrence_pattern]string=[ne][in]

How a monthly or yearly series positions its occurrence within the month.

A comma-separated list of at most 100 values.

day_of_monthweekday_occurrence

New values may be added.

filter[recurrence_start]timestamp (YYYY-MM-DDThh:mm:ssZ)=[gte][lte][null]

First moment a series may generate an occurrence.

Whether the field is null.

Search

qstring

Free-text search over title. At most one substring match per request: q together with a contains filter is 400 invalid-query-parameter.

Sorting

sortstring

Up to three keys, comma-separated, each optionally prefixed with - for descending.

Default: start

Key	Sorts by
`start`	When the event starts, latest first.
`end`	When the event ends.
`title`	Event title, alphabetically.
`occurrence_date`	The series date a separated occurrence replaces.
`recurrence_start`	First moment a series may generate an occurrence.
`recurrence_end`	Last moment a series may generate an occurrence.
`recurrence_frequency`	The unit a series repeats in, in the order day, week, month, year.
`id`	Id, ascending. An id never changes, so use this for a stable full export.
`updated_at`	Last-write timestamp; pair with the id tiebreaker for sync.

Prefix a key with - for descending.

Includes

includestring

Comma-separated names to inline, at most five.

Path	Adds	Cost
`user`	The user whose agenda this event is on.	+1

Other

trashedstring

Whether soft-deleted rows are included.

withoutdefaultwithonly

Request headers

X-Request-Idstringpattern

A correlation id of your own. It is recorded in our logs next to the server's request id but never returned: the response header always carries the server's id. A value that does not match the pattern is discarded silently, never rejected.

If-None-Matchstring

The ETag a read is conditional on. A match is answered 304 with no body.

Response 200

Returns a page of EventList rows.

dataarray of EventList

The rows, each a EventList.

meta.pagePageOptionalTotal

per_page, next_cursor, prev_cursor, total.

linksPageLinks

self, next, prev.

Each row is a EventList: 20 fields.

Headers

ETag: A weak validator (W/"…") of the rendered page.
RateLimit: The IETF httpapi-ratelimit-headers form of your remaining allowance on the tightest bucket this request touched.
RateLimit-Policy: The ceiling and window of that bucket, as <limit>;w=<seconds>.
X-Request-Id: The server-generated ULID correlating this response with our logs.

Every response also carries Cache-Control, Vary, X-Content-Type-Options, X-Plnnrly-Api-Version, X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset. Headers and versioning

idinteger

Unique identifier.

user_idintegerServer-assigned

Whose agenda the event is on. Always the authenticated user at creation time; not writable.

task_idinteger or null

Kanban task this event is planned against, or null for a plain calendar block. Only an event with a task can have time logged on it.

parent_event_idinteger or nullServer-assigned

Master event, when this row is a separated occurrence of a recurring series. Set by the server; not writable.

occurrence_datedate (YYYY-MM-DD) or nullServer-assigned

The date of the series occurrence this row replaces. Set by the server; not writable.

starttimestamp (YYYY-MM-DDThh:mm:ssZ)

When the event starts. RFC 3339 UTC.

endtimestamp (YYYY-MM-DDThh:mm:ssZ)

When the event ends. RFC 3339 UTC.

titlestring≤ 255

Event title, as shown on the calendar tile.

descriptionhtml or nullDetail only

Free-text description, authored in the rich editor. HTML, sanitised on the way in and on the way out; @-mention spans are preserved, and changing them is what notifies the people mentioned.

is_all_dayboolean

Whether the event occupies whole days rather than a time range. An all-day event is measured against the owner's working week rather than against start and end.

is_recurringboolean

Whether this row is the master of a recurring series. When true, the recurrence fields describe how occurrences are generated.

recurrence_intervalinteger or null

How many frequency units pass between occurrences: 2 with a weekly frequency is every other week.

recurrence_frequencystring or null

The unit the series repeats in.

dayweekmonthyear

New values may be added.

recurrence_patternstring or null

How a monthly or yearly series positions its occurrence within the month. Ignored for a daily or weekly frequency.

day_of_monthweekday_occurrence

New values may be added.

recurrence_starttimestamp (YYYY-MM-DDThh:mm:ssZ) or null

First moment the series may generate an occurrence.

recurrence_endtimestamp (YYYY-MM-DDThh:mm:ssZ) or null

Last moment the series may generate an occurrence; null for an open-ended series.

selected_weekdaysarray of string or nullDetail only

Weekdays a recurring event falls on. Applies to a weekly frequency; ignored otherwise.

monday
tuesday
wednesday
thursday
friday
saturday
sunday

New values may be added.

recurrence_exceptionsarray of string or nullDetail only

Dates on which this recurrence does not occur. plnnrly adds one whenever a single occurrence is separated or deleted.

created_attimestamp (YYYY-MM-DDThh:mm:ssZ)

Creation timestamp.

updated_attimestamp (YYYY-MM-DDThh:mm:ssZ)

Last-write timestamp; use for incremental sync.

deleted_attimestamp (YYYY-MM-DDThh:mm:ssZ) or null

When the event was deleted, or null while it is live. Reach a deleted event with trashed=with and undo it with POST events/{event}/actions/restore.