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

# GET /actions — Retrieve Paginated Audit Log Records

> Fetch audit log entries recording all entity mutations in Avalex. Supports optional pagination via limit. Requires the actions:read permission.

The `/actions` endpoints give you programmatic access to Avalex's audit log — a chronological record of every entity mutation performed through the platform, including license creation, customer updates, and staff activity. You can use these endpoints to build compliance reports, power dashboards, or stream events into an external logging system. Both routes require the `actions:read` permission on your token.

<Note>
  Both endpoints on this page require authentication. Include your JWT token as `Authorization: Bearer <token>`, or use HTTP Basic Auth.
</Note>

***

## GET /actions

Retrieve a list of audit log records sorted in **reverse-chronological order** (most recent first). Use the `limit` query parameter to control how many records are returned.

```http theme={null}
GET https://api.avalex.com/actions
```

**Required permission:** `actions:read`

### Query Parameters

<ParamField query="limit" type="integer">
  The maximum number of audit log records to return. Defaults to `200` if omitted. The maximum accepted value is `1000`; requests with a higher value will be capped or rejected.
</ParamField>

### Request Example

```bash theme={null}
curl "https://api.avalex.com/actions?limit=50" \
  -H "Authorization: Bearer <your-token>"
```

### Response — 200 OK

Returns an array of Action objects sorted reverse-chronologically.

<ResponseField name="id" type="string">
  The unique identifier for this audit log entry, for example `act_999`.
</ResponseField>

<ResponseField name="name" type="string">
  A dot-namespaced event name describing what occurred, for example `customers.create` or `licenses.update`. The first segment identifies the resource type; the second identifies the operation.
</ResponseField>

<ResponseField name="performedBy" type="string">
  The username of the staff member who triggered this action.
</ResponseField>

<ResponseField name="timestampEpochMillis" type="number">
  The Unix timestamp (in **milliseconds**) at which the action was recorded. Divide by 1000 to convert to seconds for use with standard date libraries.
</ResponseField>

<ResponseField name="data" type="string">
  A JSON-encoded string containing a snapshot of the affected entity at the time the action was performed. Parse this string as JSON to access individual fields.
</ResponseField>

### Response Example

```json theme={null}
[
  {
    "id": "act_999",
    "name": "customers.create",
    "performedBy": "ada",
    "timestampEpochMillis": 1723140500000,
    "data": "{\"id\":\"1\",\"name\":\"John Doe\"}"
  }
]
```

***

## GET /actions/{id}

Retrieve a single audit log record by its unique ID.

```http theme={null}
GET https://api.avalex.com/actions/{id}
```

**Required permission:** `actions:read`

### Path Parameters

<ParamField path="id" type="string" required>
  The unique identifier of the action to retrieve, for example `act_999`.
</ParamField>

### Request Example

```bash theme={null}
curl https://api.avalex.com/actions/act_999 \
  -H "Authorization: Bearer <your-token>"
```

### Response — 200 OK

Returns a single Action object with the same fields as described in the [GET /actions](#get-actions) response above.

```json theme={null}
{
  "id": "act_999",
  "name": "customers.create",
  "performedBy": "ada",
  "timestampEpochMillis": 1723140500000,
  "data": "{\"id\":\"1\",\"name\":\"John Doe\"}"
}
```

### Error Responses

| Status          | Description                                     |
| --------------- | ----------------------------------------------- |
| `404 Not Found` | No action record exists with the provided `id`. |

<Tip>
  The `data` field is a JSON-encoded **string**, not an inline object. You must parse it separately after deserializing the outer Action response. For example, in JavaScript: `JSON.parse(action.data)`.
</Tip>