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

# Events and logs

> Use events and API logs to see an object's history and who made a change.

Whenever something happens in your account — a Customer is updated, an Invoice is paid, a Tenancy is activated — Yorlet records an **event**. Events are the history of your objects. **Logs** are the API requests that caused those changes, including which team member or API key made them.

Use them together: events tell you *what* changed, and the linked log tells you *who* did it and *how*.

## What is an event?

An event is a snapshot of a record at the moment something happened. Each event has:

* A **type**, such as `customer.updated` or `invoice.paid`. See the [full list of event types](/api/events).
* The **object** as it was when the event occurred.
* **Previous attributes** on update events — the fields that changed and their values before the change.
* A **request**, including who caused it and the log ID for the API call.

Events are also sent to [webhook endpoints](/development/webhooks) you subscribe, and can start a [workflow](/business-automation/workflows/triggers).

## See an object's history

Most records in the Dashboard include an **Events** table at the bottom of the page. This is the history of that object: created, updated, paid, cancelled, and so on.

To review a Customer's history, follow these steps:

1. Open the [Customers](https://dashboard.yorlet.com/customers) page and select a Customer.
2. Scroll to **Events**.
3. Click an event to open it. You will see the time, who caused it, the event data, and any previous attributes.

The same **Events** table appears on Invoices, Subscriptions, Tenancies, Applications, Units, Buildings, Payments, and other records.

<Tip>
  Open [Events](https://dashboard.yorlet.com/developers/events) to browse every event in the account. Use the **Object ID** filter to find events that involve a specific record, or the **Type** filter to narrow to a type such as `invoice.paid`.
</Tip>

## See who made a change

The event tells you what changed. The linked **log** tells you who made the request, from which IP address, and with which request body.

To trace a change back to a person or API key, follow these steps:

1. Open the event — either from the object's **Events** table or from [Events](https://dashboard.yorlet.com/developers/events).
2. Check **Actor**. This is the kind of principal that caused the event:
   * **Dashboard user** — a team member in the Dashboard.
   * **API** — a secret or restricted API key.
   * **Agent** — an [agent key](/business-automation/ai/agent-keys).
   * **System** — Yorlet itself, for example a subscription generating an invoice.
3. Click **Source** (Dashboard, API, or Customer portal). This opens the log for that request.
4. On the log, read:
   * **User** — the team member's email, when the request came from the Dashboard.
   * **Key** — the API key ID, when the request used a key.
   * **IP address** and **User agent**.
   * **Request body** — the payload that was sent (for `POST` requests).
   * **Response body** — what Yorlet returned.

The event's `request.id` is the same as the log ID (it starts with `req_`). You can also open a log directly at [Logs](https://dashboard.yorlet.com/developers/logs).

<Note>
  Logs list mutating requests (`POST` and `DELETE`). Reads (`GET`) are not stored. Some events are created by Yorlet in the background and have no log — for example a Subscription generating an Invoice. Those events show **System** as the actor.
</Note>

### Filter logs by object

To see every mutating request that touched a record, without starting from an event:

1. Go to [Logs](https://dashboard.yorlet.com/developers/logs).
2. Filter by **Object ID** and paste the record's ID.
3. Use the **Succeeded** and **Failed** tabs to separate successful changes from errors.

Each row shows the HTTP method, URL, status, and time. Click a row to inspect the request and response.

## Event object

When you retrieve an event from the API, or inspect one in the Dashboard, the payload looks like this:

```json theme={"theme":"dracula"}
{
  "id": "evt_1a2b3c4d",
  "object": "event",
  "api_version": "2025-08-21",
  "created": 1718712000,
  "type": "customer.updated",
  "data": {
    "object": {
      "id": "cus_123",
      "object": "customer",
      "email": "ada@example.com"
    },
    "previous_attributes": {
      "email": "ada@old.example.com"
    }
  },
  "request": {
    "actor": {
      "type": "user",
      "id": "user_123",
      "name": "ada@yourfirm.com",
      "key_id": null,
      "key_type": null
    },
    "customer_portal": false,
    "from_dashboard": true,
    "id": "req_abc",
    "idempotency_key": null
  }
}
```

| Field                      | Description                                                                                                                               |
| -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `id`                       | Unique identifier for the event.                                                                                                          |
| `type`                     | The event type, for example `customer.updated`. See the [full list](/api/events).                                                         |
| `data.object`              | The record the event relates to, at the time the event occurred.                                                                          |
| `data.previous_attributes` | For `*.updated` events, the keys that changed and their previous values. `null` otherwise.                                                |
| `request.id`               | The API request ID. Matches the log in [Logs](https://dashboard.yorlet.com/developers/logs). `null` when Yorlet created the event itself. |
| `request.from_dashboard`   | `true` when a team member made the change in the Dashboard.                                                                               |
| `request.customer_portal`  | `true` when the change came from a customer-facing portal.                                                                                |
| `request.actor`            | Who caused the event. `null` on events created before actor attribution existed.                                                          |
| `request.idempotency_key`  | The [idempotency key](/api/idempotency) on the request, if one was sent.                                                                  |

### Actor

`request.actor` identifies the principal that caused the event:

| `type`    | Meaning                                                                 |
| --------- | ----------------------------------------------------------------------- |
| `user`    | A Dashboard team member. `id` is the user ID and `name` is their email. |
| `api_key` | A secret or restricted API key. `key_id` is the key that was used.      |
| `agent`   | An [agent key](/business-automation/ai/agent-keys).                     |
| `system`  | Yorlet, not a person or key.                                            |

## Events API

List and retrieve events with a [secret key](/development/api-keys) that has the `events.read` permission.

### List events for an object

Pass `object_id` to return events whose primary record is that object — the same set you see on the object's **Events** table:

```shell theme={"theme":"dracula"}
curl "https://api.yorlet.com/v1/events?object_id=cus_123" \
  -H "Authorization: Bearer {access_token}"
```

Pass `related_object` to include events that mention the ID even when it is not the primary record. For example, an `invoice.paid` event for a Customer's Invoice:

```shell theme={"theme":"dracula"}
curl "https://api.yorlet.com/v1/events?related_object=cus_123" \
  -H "Authorization: Bearer {access_token}"
```

The Dashboard **Object ID** filter on [Events](https://dashboard.yorlet.com/developers/events) uses `related_object`.

### Filter by type

Match an exact type, or use a trailing `*` to match a prefix:

```shell theme={"theme":"dracula"}
curl "https://api.yorlet.com/v1/events?type=invoice.paid" \
  -H "Authorization: Bearer {access_token}"
```

```shell theme={"theme":"dracula"}
curl "https://api.yorlet.com/v1/events?type=invoice.*" \
  -H "Authorization: Bearer {access_token}"
```

### Retrieve an event

```shell theme={"theme":"dracula"}
curl https://api.yorlet.com/v1/events/{id} \
  -H "Authorization: Bearer {access_token}"
```

Events are returned newest first. Use `limit` (default 20, maximum 50) and `offset` to page through results.

<Tip>
  To reconstruct user activity in your own tools, list events for the object, then join each `request.id` to the log in the Dashboard. The log has the team member's email and the raw request body; the event has the resulting object and `previous_attributes`.
</Tip>

## Events, logs, and the activity log

These are three different records of activity:

|                  | What it shows                                                                       | Where to find it                                                                                                                |
| ---------------- | ----------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| **Events**       | What happened to a record (created, updated, paid, and so on).                      | The **Events** table on the record, [Events](https://dashboard.yorlet.com/developers/events), or `GET /v1/events`.              |
| **Logs**         | The mutating API request behind a change — who, from where, and with which payload. | [Logs](https://dashboard.yorlet.com/developers/logs), or the **Source** link on an event.                                       |
| **Activity log** | Changes to account *settings*, not to Customers, Invoices, or other records.        | [Settings → Security → Activity](https://dashboard.yorlet.com/settings/security/activity). See [Activity](/account/audit-logs). |