> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lumos.com/llms.txt
> Use this file to discover all available pages before exploring further.

# The Identity Event object

> A detected change to one field of an identity, the filters for the list, and how to tell when you've read every page.

An identity event records one change that Lumos detected on an identity: which field changed, its
old and new values, and when Lumos detected the change. A [user](https://docs.lumos.com/reference/v1/objects/user.md) is one
kind of identity. A status change, a new email address, and an identity joining a group each
produce an event. A change to two fields at once produces two events.

Events are read-only. You read them through one endpoint,
[List Identity Events](https://docs.lumos.com/api-reference/v1/identity-events/list-identity-events.md).

```json The Identity Event object theme={null}
{
  "id": "t2wKCZIBqX3pLm7dV0aE",
  "user_id": "3c4d5e6f-7081-9012-cdef-123456789012",
  "detected_time": "2026-09-24T18:02:11.482000Z",
  "changed_field": "Email",
  "old_field_value": "jane@old.example.com",
  "new_field_value": "jane.smith@example.com"
}
```

## Attributes

| Field | Type | Description |
| - | - | - |
| `id` | string | Unique identifier for the event. Always present. |
| `user_id` | string | The [user](https://docs.lumos.com/reference/v1/objects/user.md) `id` of the identity whose field changed. Always present. |
| `detected_time` | string | When Lumos detected the change, in ISO 8601 format. Always present. |
| `changed_field` | string | The label of the field that changed, such as `Email`, `Status`, or `Group Membership`, or a custom attribute's label. Always present. |
| `old_field_value` | string or null | The field's value before the change. |
| `new_field_value` | string or null | The field's value after the change. |

A group membership change shows the group's name, and a custom attribute change shows the
attribute's value.

## Who can read identity events

Of the built-in roles, Admin and Read Only Admin can list identity events.

## Filtering

[List Identity Events](https://docs.lumos.com/api-reference/v1/identity-events/list-identity-events.md) returns events
newest first, by `detected_time`. Four filters narrow the list:

| Filter | Effect |
| - | - |
| `identity_ids` | Events for these identities, by user `id`. An ID that doesn't match an identity in your organization returns `404`. |
| `changed_fields` | Events for these fields, named by the labels `changed_field` returns. |
| `start_time` | Events detected at or after this timestamp. |
| `end_time` | Events detected at or before this timestamp. |

`changed_fields` matches labels exactly, including case, so `Status` works and `status` returns
`400`. The built-in labels are `Given Name`, `Family Name`, `Full Name`, `Email`, `Status`,
`Identity Type`, `Email Is Lumos Generated`, `Identity Source App`, and `Group Membership`. Any
other label must be the label of one of your custom attributes. A label that matches neither
returns `400`, and the error message lists the built-in labels.

```bash theme={null}
curl -s 'https://api.lumos.com/v1/identity-events?changed_fields=Status&changed_fields=Group%20Membership&start_time=2026-09-01T00:00:00Z' \
  --header 'Authorization: Bearer lsk_your_token'
```

## Reading to the end

`page_size` defaults to 100 and is capped at 100. Every page with events has a `next_page_token`,
including the last one, so the request after the last page returns no events, and its
`next_page_token` is missing or `null`.

A page can also be empty while `next_page_token` is still set.
[Short and empty pages](https://docs.lumos.com/reference/v1/pagination.md#short-and-empty-pages) explains when to stop.

## Endpoints

| Endpoint | Path |
| - | - |
| [List Identity Events](https://docs.lumos.com/api-reference/v1/identity-events/list-identity-events.md) | `GET /v1/identity-events` |