Querying events

Use POST /api/events/query when you need to find multiple events. The request body controls the authorization scope, filters, sort order, and page size.

This guide queries one project with an API key. Use the credential type and authorization scope issued for your integration, as described in the quickstart and API conventions.

Before you begin

You need:

the EventPoint API base URL;
an API key assigned to the project; and
the project’s GUID.

API_URL="https://api.example.com"
API_KEY="your-issued-api-key"
PROJECT_ID="00000000-0000-0000-0000-000000000000"

Make a basic query

The projects array limits the query to projects the credential is authorized to access. Page numbers start at 1 in this example.

curl --request POST \
  --url "$API_URL/api/events/query" \
  --header "Accept: application/json" \
  --header "Content-Type: application/json" \
  --header "x-api-key: $API_KEY" \
  --data "{
    \"page\": 1,
    \"itemsPerPage\": 25,
    \"sort\": \"start\",
    \"sortDir\": \"Asc\",
    \"projects\": [\"$PROJECT_ID\"]
  }"

For an external integration, the request must include at least one authorized scope: organizations, projects, eventIds, topLevelIds, or parentIds. The request is rejected if the credential cannot access every identifier in the selected scope.

Understand the response

A successful response is a paged query result:

{
  "page": 1,
  "itemsPerPage": 25,
  "count": 57,
  "numberOfPages": 3,
  "data": [
    {
      "id": "11111111-1111-1111-1111-111111111111",
      "name": "Opening session",
      "start": "2026-09-15T13:00:00Z"
    }
  ]
}

The event objects can contain more fields than this shortened example. Use the generated operation reference as the source of truth for the current request and response schemas.

Filter by text and time

Add terms, startUtc, and endUtc to find matching events in a UTC time window:

{
  "page": 1,
  "itemsPerPage": 25,
  "sort": "start",
  "sortDir": "Asc",
  "projects": ["00000000-0000-0000-0000-000000000000"],
  "terms": "workshop",
  "startUtc": "2026-09-15T00:00:00Z",
  "endUtc": "2026-09-16T00:00:00Z"
}

Common filters include:

Field	Purpose
`terms`	Search text associated with an event.
`eventTypes`	Include events with selected event-type GUIDs.
`categories`	Include events associated with selected category GUIDs.
`parentIds`	Find child events for selected parent-event GUIDs.
`topLevelOnly`	Limit results to top-level events.
`publish`	Filter by published state.
`timePeriodFilter`	Use `All`, `Upcoming`, or `Past`.

Omit unused optional filters instead of sending empty values. This makes the request easier to read and avoids unintentionally changing the query.

Query from JavaScript

The example below keeps credentials on a trusted server and checks the response before reading the result.

const response = await fetch(`${process.env.API_URL}/api/events/query`, {
  method: 'POST',
  headers: {
    Accept: 'application/json',
    'Content-Type': 'application/json',
    'x-api-key': process.env.API_KEY,
  },
  body: JSON.stringify({
    page: 1,
    itemsPerPage: 25,
    sort: 'start',
    sortDir: 'Asc',
    projects: [projectId],
    timePeriodFilter: 'Upcoming',
  }),
});

if (!response.ok) {
  const details = await response.text();
  throw new Error(`Event query failed (${response.status}): ${details}`);
}

const contentType = response.headers.get('content-type') ?? '';
if (!contentType.includes('application/json')) {
  const details = await response.text();
  throw new Error(`The API returned an unexpected response: ${details}`);
}

const result = await response.json();

for (const event of result.data ?? []) {
  console.log(event.name);
}