events/list-events is the ability that answers calendar questions. Date range, venue, organizer, category, featured flag, free-text search — filter on any of them, and every event comes back with its dates, timezone, venue and organizers already resolved.
The date filters accept anything WordPress can parse, so what is on next week is a single call rather than a date calculation followed by a query.
At a glance
| Ability | events/list-events |
| Toolset | The Events Calendar — toolset/events-calendar |
| Group | The Events Calendar › Events |
| Requires | The Events Calendar, active on the site |
| Capability | manage_options |
| Safety | Read-only — changes nothing |
| Repeatable | Idempotent — running it twice leaves the same result |
| Ships in | AcrossAI Abilities Manager 0.0.34 and later |
How it works
The Events Calendar does not store an event as a post with two meta fields. It keeps local start and end, UTC start and end, a timezone string and a timezone abbreviation, and it mirrors the occurrence into its own tables so that month and list views can be queried without touching post meta at all.
Reading that by hand means joining a table most people do not know exists. This ability goes through the calendar’s own query layer instead, so the results are the same ones the calendar’s own views would produce — including the parts that are easy to get wrong, like an event that spans midnight counting as running on both days.
Every result arrives resolved. The venue is a name and address, not an ID you then have to look up; the organizers are names and contact details; the cost is the string the site actually displays. One call, not one call plus a lookup per row.
Input
| Name | Type | Required | What it is |
|---|---|---|---|
starts_after | string | No | Only events starting on or after this date. Accepts anything strtotime() understands — 2026-11-01 or next monday both work. |
starts_before | string | No | Only events starting before this date. |
ends_after | string | No | Only events ending after this date. Use it to catch multi-day events already in progress. |
venue | integer | No | Only events at this venue. |
organizer | integer | No | Only events with this organizer. |
category | string | integer | No | Event category slug or term ID. |
featured | boolean | No | Only featured events. |
search | string | No | Free-text search over title and content. |
status | string | No — defaults to publish | Post status, or any to include drafts and pending events. |
page | integer | No — defaults to 1 | 1-based page number. |
per_page | integer | No — defaults to 20 | Results per page, capped at 100. |
What comes back
| Name | Type | What it is |
|---|---|---|
events | array | One entry per event: title, status, local and UTC start and end, timezone, all-day and multiday flags, cost, featured flag, resolved venue and organizers, and categories. |
total | integer | Total matching events, before paging. |
page | integer | The page returned. |
per_page | integer | The page size used. |
success | boolean | Whether the call completed. |
message | string | A one-line summary of what happened, suitable for showing a human. |
error_code | string | Present only on failure — a stable machine-readable reason, such as a missing field, a wrong field type or an unmet confirmation. |
Example
Ask your assistant:
What events are on next week, and where are they being held?
It resolves to one call:
{
"ability": "events/list-events",
"parameters": {
"starts_after": "next monday",
"starts_before": "next monday +7 days",
"status": "any"
}
}Worth knowing
- An event that started yesterday and ends tomorrow will not match
starts_afterset to today. Addends_afterwhen you want events currently running. - Times come back twice over: local with the event’s timezone, and UTC. Compare across events in UTC; show a human the local pair.
- Recurring events appear here as their occurrences. Editing a series is out of scope for this suite.
- Drafts are excluded unless you ask for them. Event sites routinely hold half-finished events, so the default is the published calendar.
Related abilities
- Get Event — one event in full
- List Venues — find the venue ID to filter on
- List Event Categories — find a category and its event count
Get the plugins:
AcrossAI Abilities Manager · AcrossAI MCP Manager
Browse the rest: Every ability, by category