Events

List and retrieve events from your WorkOS environment

Overview

The Events API allows you to retrieve events that have occurred in your WorkOS environment. Events represent actions and state changes across all WorkOS services.

Methods

listEvents

Retrieves a list of events based on the provided filter criteria.

options · ListEventOptions · required

Configuration options for listing events

Show properties

events · EventName[] · required

Array of event names to filter by

rangeStart · string

ISO 8601 datetime string for the start of the event range

rangeEnd · string

ISO 8601 datetime string for the end of the event range

limit · number

Maximum number of events to return (default: 10)

after · string

Cursor for pagination to fetch the next page of results

organizationId · string

Filter events by a specific organization ID

List<Event> · object

A paginated list of events

Show properties

data · Event[]

Array of event objects

listMetadata · object

Pagination metadata including before and after cursors

Example

import { WorkOS } from '@workos-inc/node';

const workos = new WorkOS('sk_example_123456789');

const events = await workos.events.listEvents({
  events: ['user.created', 'user.updated'],
  rangeStart: '2024-01-01T00:00:00Z',
  rangeEnd: '2024-12-31T23:59:59Z',
  limit: 20,
  organizationId: 'org_01H8Z9Q2Z3Y4X5W6V7U8T9S0R1',
});

console.log(events.data);

Response

{
  "data": [
    {
      "id": "event_01H8Z9Q2Z3Y4X5W6V7U8T9S0R1",
      "event": "user.created",
      "data": {
        "id": "user_01H8Z9Q2Z3Y4X5W6V7U8T9S0R1",
        "email": "[e-mail]"
      },
      "createdAt": "2024-01-15T10:30:00Z"
    }
  ],
  "listMetadata": {
    "after": "event_01H8Z9Q2Z3Y4X5W6V7U8T9S0R1",
    "before": null
  }
}

Related Resources

Webhooks

Configure webhooks to receive events in real-time

Audit Logs

Track security and compliance events