<!-- llms.txt: https://workos.com/llms.txt -->

# Events

Events represent activity that has occurred within WorkOS or within third-party identity and directory providers. They are used to keep your app in sync with WorkOS data.
For more details on consuming events in your app, check out the [data syncing](https://workos.com/docs/events/data-syncing) guide.

Refer to the [Events](https://workos.com/docs/events) page for a full list of events that WorkOS emits.

## List events

List events for the current environment.

:::code-group

```bash language="curl" title="Request" tab="1"
curl "https://api.workos.com/events" \
  --header "Authorization: Bearer sk_example_123456789" \
  -G \
  -d events=dsync.user.created,dsync.user.updated
```

```js language="js" title="Request" tab="1"
import { WorkOS } from '@workos-inc/node';

const workos = new WorkOS(process.env.WORKOS_API_KEY);

const listOfEvents = await workos.events.listEvents({
  events: [
    'dsync.activated',
    'dsync.deleted',
    'dsync.user.created',
    'dsync.user.updated',
    'dsync.user.deleted',
  ],
});
```

```rb language="ruby" title="Request" tab="1"
require "workos"

WorkOS.configure do |config|
  config.api_key = "sk_example_123456789"
end

WorkOS.client.events.list_events(events: ["dsync.user.created", "dsync.user.updated"])
```

```py language="python" title="Request" tab="1"
from workos import WorkOSClient

client = WorkOSClient(api_key="sk_example_123456789", client_id="client_123456789")

client.events.list_events(events=["dsync.user.created", "dsync.user.updated"])
```

```go language="go" title="Request" tab="1"
package main

import (
	"context"

	"github.com/workos/workos-go/v10"
)

func main() {
	client := workos.NewClient("sk_example_123456789")

	_, err := client.Events().List(context.Background(), &workos.EventsListParams{
		Events: []any{"dsync.user.created", "dsync.user.updated"},
	})
	if err != nil {
		panic(err)
	}
}
```

```php language="php" title="Request" tab="1"
<?php

use WorkOS\WorkOS;

$workos = new WorkOS(
    apiKey: "sk_example_123456789",
    clientId: "client_123456789",
);

$workos
    ->events()
    ->listEvents(events: ["dsync.user.created", "dsync.user.updated"]);
```

```java language="java" title="Request" tab="1"
import com.workos.WorkOS;
import com.workos.events.EventsApi.ListEventsOptions;

WorkOS workos = new WorkOS("sk_example_123456789");

ListEventsOptions options =
    ListEventsOptions.builder()
        .events(List.of("dsync.user.created", "dsync.user.updated"))
        .build();

workos.events.listEvents(options);
```

```cs language="dotnet" title="Request" tab="1"
using WorkOS;

var client = new WorkOSClient(new WorkOSOptions {
    ApiKey = "sk_example_123456789",
    ClientId = "client_123456789",
});

await client.Events.ListAsync(new EventsListOptions {
    Events = new[] { "dsync.user.created", "dsync.user.updated" },
});
```

```rust language="rust" title="Request" tab="1"
use workos::Client;
use workos::events::ListEventsParams;

#[tokio::main]
async fn main() -> Result<(), workos::Error> {
    let client = Client::builder()
        .api_key("sk_example_123456789")
        .client_id("client_123456789")
        .build();

    let _result = client
        .events()
        .list_events(
            ListEventsParams {
                events: vec!["dsync.user.created".into(), "dsync.user.updated".into()],
                ..Default::default()
            }
        )
        .await?;

    Ok(())
}
```

```json language="json" title="Response" tab="2"
{
  "object": "list",
  "data": [
    {
      "object": "event",
      "id": "event_01EHZNVPK3SFK441A1RGBFSHRT",
      "event": "dsync.user.created",
      "data": {
        "id": "directory_user_01E1JG7J09H96KYP8HM9B0G5SJ",
        "directory_id": "directory_01ECAZ4NV9QMV47GW873HDCX74",
        "organization_id": "org_01EZTR6WYX1A0DSE2CYMGXQ24Y",
        "state": "active",
        "email": "veda@foo-corp.com",
        "emails": [
          {
            "primary": true,
            "type": "work",
            "value": "veda@foo-corp.com"
          }
        ],
        "idp_id": "2836",
        "object": "directory_user",
        "username": "veda@foo-corp.com",
        "last_name": "Torp",
        "first_name": "Veda",
        "raw_attributes": {},
        "custom_attributes": {},
        "created_at": "2021-06-25T19:07:33.155Z",
        "updated_at": "2021-06-25T19:07:33.155Z"
      },
      "created_at": "2021-06-25T19:07:33.155Z",
      "context": {}
    }
  ],
  "list_metadata": {
    "after": "event_01EHZNVPK3SFK441A1RGBFSHRT"
  }
}
```

:::

### event

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `object` | "event" | Yes | Distinguishes the Event object. |
| `id` | string | Yes | Unique identifier for the Event. |
| `event` | string | Yes | The type of event that occurred. |
| `data` | object | Yes | The event payload. |
| `created_at` | string | Yes | An ISO 8601 timestamp. |
| `context` | object | No | Additional context about the event. |

### GET /events

#### Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `before` | string | No | An object ID that defines your place in the list. When the ID is not present, you are at the end of the list. For example, if you make a list request and receive 100 objects, ending with `"obj_123"`, your subsequent call can include `before="obj_123"` to fetch a new batch of objects before `"obj_123"`. |
| `after` | string | No | Pagination cursor to receive records after a provided event ID. Mutually exclusive with the `range_start` parameter. |
| `limit` | integer | No | Maximum number of records to return. Accepts values between `1` and `100`. Default is `10`. |
| `order` | "normal" \| "desc" \| "asc" | No | Order the results by the creation time. Supported values are `"asc"` (ascending), `"desc"` (descending), and `"normal"` (descending with reversed cursor semantics where `before` fetches older records and `after` fetches newer records). Defaults to `normal`. |
| `events` | string[] | Yes | Filter to only return events of particular types. |
| `range_start` | string | No | ISO 8601 formatted date range start for a stream of events. Can be provided without `range_end` to fetch all events since `range_start`. Mutually exclusive with the `after` parameter. |
| `range_end` | string | No | ISO 8601 formatted date range end for a stream of events. |
| `organization_id` | string | No | Filter to only return events belonging only to specific Organizations. User events (e.g user.created) will not be Organization specific. |