---
title: "List audit events"
method: GET
path: "/audit-events"
tags: ["Audit Events"]
---

# List audit events

`GET /audit-events`

## Request

- Base URL: `https://app.amperity.com/api`
- URL: `https://app.amperity.com/api/audit-events`
- Auth: HTTP bearer
- TypeScript: <https://skmtc.dev/amperity/apis/amperity-api/docs/audit-events/get.ts> (a function with typed inputs; its response is checked against the schema)

Return a log of user activity that occurred in your tenant. Each response may contain up to 1000 audit events. When requesting events for a production tenant, all events (including events from sandboxes created for that tenant) are included in the response. When requesting events from a sandbox, only events from that sandbox are included in the response.

## Query parameters

- `api_version` string
- `with_total` boolean
- `limit` integer
- `next_token` string
- `happened_from` string, date-time
- `happened_to` string, date-time

## Headers

- `Amperity-Tenant` string, required
- `Api-Version` string, required

## Response `200`

List of audit events

- AuditEventListEnvelope: Paginated list of AuditEvents
  - `data` AuditEvent[], required: AuditEvent items on this page
    - `event_id` string, required: The unique identifier for the event.
    - `event_type` string, required: The type of event.
    - `happened_at` string, date-time, required: The date and time at which the action occurred. Dates and times are in ISO-8601 format and in UTC.
    - `object_id` string, required: The identifier for the object against which the action occurred.
    - `object_name` string, required: A composed string that describes the object(s) for which the action occurred.
    - `origin_ip` string, required: The IP address that is associated with the user who initiated the action.
    - `principal_email` string, required: The email address for the user who initiated the action.
    - `principal_id` string, required: The identifier for the user who initiated the action. This user may be an API key or a non-human user.
    - `principal_name` string, required: The friendly name of the user associated with the activity, if available, otherwise the email address or API key.
    - `session_id` string, required: The identifier for the session in which the action occurred.
    - `tenant` string, required: The unique identifier for the tenant.
    - `tenant_family` string, required: The unique identifier for the tenant family
    - `user_agent` string, required: The user agent string of the client that initiated the action.
  - `next_token` string: The cursor value to use in a subsequent request to return the next page of results.
  - `total` integer: The total count of all results. This property is only returned when `with_total` is set to `true` in a request.

## Other responses

- `400`: Bad Request
- `401`: Authentication Required
- `403`: Not Authorized
- `404`: Not Found
- `405`: Method Not Allowed
- `500`: Internal Error

---

[API](https://skmtc.dev/amperity/apis/amperity-api.md) - [All operations](https://skmtc.dev/amperity/apis/amperity-api/llms.txt) - [OpenAPI document](https://skmtc.dev/amperity/apis/amperity-api/revisions/97ccd051d9dc?raw)