# Audit Log Query

This page describes how to query account-level audit logs through the API, with support for filtering by time range and operator. It is intended for troubleshooting and compliance review.

## URI

GET /audit_logs

## Permission and Rate Limit

The API key must have the `Audit_Log_Query` permission. This endpoint can be requested up to 60 times per hour per API key.

## Query Parameters

| Parameter   | Type    | Required | Default     | Description                                                                                                                                           |
| ----------- | ------- | -------- | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| `auditType` | String  | No       | —           | Exact-match filter by audit type, for example `PLATFORM_API_KEY_CREATED`.                                                                             |
| `operator`  | String  | No       | —           | Filter by operator. Accepted values: `system` (system operations), owner email, subuser email, or a 16-character alphanumeric appKey.                  |
| `startTime` | String  | No       | —           | Query start time in `YYYY-MM-DD HH:MM:SS` format. Cannot be earlier than 90 days ago (midnight UTC).                                                  |
| `endTime`   | String  | No       | —           | Query end time in `YYYY-MM-DD HH:MM:SS` format. Must not be later than the current time.                                                              |
| `_page`     | Integer | No       | `1`         | Page number. Minimum value: `1`.                                                                                                                      |
| `_limit`    | Integer | No       | `20`        | Number of items per page. Minimum value: `1`.                                                                                                         |
| `_sort`     | String  | No       | `auditTime` | Sort field.                                                                                                                                           |
| `_order`    | String  | No       | `desc`      | Sort order. Accepted values: `asc`, `desc`.                                                                                                           |

::: warning Time Range Limit
`startTime` cannot be earlier than midnight UTC 90 days ago. Requests with an earlier `startTime` will return `400`.
:::

## Request Example

Use the API key as the username and the API secret as the password for Basic Auth.

```bash
curl -u key:secret -X GET "{api}/audit_logs?startTime=2026-04-15%2016:00:00&endTime=2026-04-22%2016:00:00&operator=system&_page=1&_limit=20"
```

## Response Example

```json
{
  "items": [
    {
      "auditTime": "2026-04-30 10:30:00",
      "auditType": "PLATFORM_API_KEY_CREATED",
      "ip": "203.0.113.8",
      "description": "Created Platform API Key: xxx.",
      "userType": "api",
      "appKey": "app_k_xxx",
      "subuserID": null,
      "userID": "user_xxx",
      "operator": "app_k_xxx"
    }
  ],
  "meta": {
    "page": 1,
    "limit": 20,
    "count": 37
  }
}
```

## Response Fields

| Field         | Type   | Description                                                                                             |
| ------------- | ------ | ------------------------------------------------------------------------------------------------------- |
| `auditTime`   | String | Time of the audit event in `YYYY-MM-DD HH:MM:SS` format.                                               |
| `auditType`   | String | Audit event type.                                                                                       |
| `ip`          | String | IP address of the operation source.                                                                     |
| `description` | String | Description of the operation.                                                                           |
| `userType`    | String | Operator type. Enum: `system`, `user` (owner), `subuser`, `api` (API key).                             |
| `appKey`      | String | The API key used for the operation. Only present when `userType` is `api`.                              |
| `subuserID`   | String | Subuser ID. Only present when `userType` is `subuser`; otherwise `null`.                                |
| `userID`      | String | Account ID.                                                                                             |
| `operator`    | String | Resolved display value of the operator: owner email, subuser email, `system`, or appKey.               |

## Error Responses

| HTTP Status | Description                                                                     |
| ----------- | ------------------------------------------------------------------------------- |
| `400`       | Invalid parameters, for example an invalid time format or a range over 90 days. |
| `401`       | Unauthorized. The API key is missing or invalid.                                |
| `403`       | Forbidden. The API key does not have the `Audit_Log_Query` permission.          |
| `429`       | Too many requests. Exceeded the rate limit of 60 requests per hour per API key. |