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

# Introduction to Audit Logs

> Retrieve a record of actions performed in your workspace — who did what, when, and from where.

The Audit Logs API can be used to:

* Feed workspace activity data into your SIEM or other monitoring tools
* Track changes across your organization, from workspace settings and model keys to role changes, failed login attempts, and more
* Build custom dashboards and reports for workspace activity

## Prerequisites

To use the Audit Logs API, you need:

* **Workspace Admin Permission**: Only workspace administrators can create API keys with audit log permissions.
* **API Key with `AUDIT_LOG_API` Scope**: Your API key must have the dedicated audit log scope enabled.

<Warning>
  **Important Security Notice**: Users with access to an API key with the **AUDIT\_LOG\_API** scope can read all audit log data for the workspace, including IP addresses, user actions, and configuration changes. Only grant this permission to trusted users.
</Warning>

## Retention

Audit log entries are retained for **90 days**. Make sure to export or forward any data you need before it expires.

## Available Endpoint

```
GET /audit-logs/{workspace_id}
```

## Authentication

All API requests require Bearer token authentication:

```bash theme={null}
Authorization: Bearer YOUR_API_KEY
```

## The Audit Log Entry

Every audit log entry describes an **actor** taking an **action** on an **entity**. Here's what each entry contains:

| Field                                  | Description                                                                                                                  |
| -------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| `actor_id`, `actor_type`, `actor_name` | Who performed the action. Actor types: `USER`, `API_KEY`, `SYSTEM`, `SCIM`                                                   |
| `action`                               | What happened, in dot notation (e.g. `user.updated`, `workspace.created`, `api_keys.deleted`)                                |
| `entity_type`, `entity_id`             | Which resource was affected (e.g. `User`, `Workspace`, `Group`, `IntegrationConnection`)                                     |
| `created_at`                           | When the event occurred                                                                                                      |
| `ip_address`, `user_agent`             | Where the request came from                                                                                                  |
| `changes`                              | A `before`/`after` diff of changed fields (for update events)                                                                |
| `snapshot`                             | Full entity snapshot or additional event metadata (e.g. on delete/create events, or extra context like failed login details) |

## Pagination

The API uses **cursor-based pagination**. Each response includes a `next_cursor` field — pass it as the `cursor` query parameter in your next request to get the following page. When `next_cursor` is `null`, you've reached the end.

```bash theme={null}
# First request
curl "https://api.langdock.com/audit-logs/{workspace_id}?limit=50" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Next page
curl "https://api.langdock.com/audit-logs/{workspace_id}?limit=50&cursor={next_cursor}" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

## Filtering

You can narrow results using query parameters:

| Parameter     | Type       | Description                                      |
| ------------- | ---------- | ------------------------------------------------ |
| `from`        | `datetime` | Start of date range (ISO 8601)                   |
| `to`          | `datetime` | End of date range (ISO 8601)                     |
| `entity_type` | `string`   | Filter by entity type (e.g. `User`, `Workspace`) |
| `actor_id`    | `uuid`     | Filter by the actor who performed the action     |
| `limit`       | `integer`  | Items per page (default 50, max 50)              |
| `cursor`      | `uuid`     | Cursor from previous response for pagination     |

## Error Handling

| Status Code | Description                                                          |
| ----------- | -------------------------------------------------------------------- |
| `400`       | Invalid request parameters (e.g. malformed date, invalid UUID)       |
| `401`       | Missing or invalid API key                                           |
| `403`       | API key lacks `AUDIT_LOG_API` scope, or `workspace_id` doesn't match |
| `429`       | Rate limit exceeded — back off and retry                             |
| `500`       | Internal server error                                                |

<Info>
  Langdock intentionally blocks browser-origin requests to protect your API key and ensure your applications remain secure. For more information, please see our guide on [API Key Best Practices](/en/admin/ai-adoption-and-rollout/best-practices/api-key-best-practices).
</Info>