Audit Trail

The /audit-trail endpoint allows you to query audit events that track actions performed across your account. Every create, update, delete, publish, and other mutation is recorded with details about who performed the action, what resource was affected, and when it happened.

List Audit Events

/api/v1/audit-trail

Method: GET

Requirements: User must have project:admin or account:admin permission. Project admins can only view events within their own project.

Headers

Header	Value	Description
`Authorization`	`Bearer <YOUR_JWT_TOKEN>`	JWT token for authentication

Query Parameters

Filters

Parameter	Data Type	Description
`actions`	`string`	Comma-separated list of action types to filter by. Values: `create`, `update`, `delete`, `bulk_update`, `bulk_delete`, `attach`, `detach`, `publish`, `unpublish`.
`resourceTypes`	`string`	Comma-separated list of resource types to filter by (e.g. `interaction`, `object`, `workflow`).
`resourceId`	`string`	Filter by a specific resource ID.
`principalId`	`string`	Filter by principal ID (API keys, service accounts).
`principalUserId`	`string`	Filter by principal user ID (human users).
`projectId`	`string`	Filter by project ID. Only available to account admins; project admins are automatically scoped to their project.

Date Range

Parameter	Data Type	Description
`from`	`string`	Start time as an ISO 8601 string (e.g. `2025-01-01T00:00:00Z`).
`to`	`string`	End time as an ISO 8601 string (e.g. `2025-01-31T23:59:59Z`).

Pagination

Parameter	Data Type	Description
`limit`	`number`	Number of events to return. Default: `50`, max: `200`.
`offset`	`number`	Number of events to skip for pagination. Default: `0`.

Example Response

{
  "events": [
    {
      "event_type": "audit",
      "action": "update",
      "resource_type": "interaction",
      "resource_id": "6789abcd0123ef4567890123",
      "timestamp": "2025-01-15T14:32:10.000Z",
      "request_id": "req_abc123def456",
      "status": 200,
      "success": true,
      "principal_id": "key_abc123",
      "principal_type": "apikey",
      "principal_user_id": "user_xyz789",
      "roles": ["project_admin"],
      "account_id": "acct_001",
      "project_id": "proj_001",
      "tenant_id": "tenant_001",
      "account_name": "My Account",
      "project_name": "My Project"
    }
  ],
  "hasNext": true,
  "limit": 50,
  "offset": 0
}

AuditTrailEvent Fields

Field	Data Type	Description
`event_type`	`string`	Always `"audit"`.
`action`	`AuditAction`	The action that was performed. One of: `create`, `update`, `delete`, `bulk_update`, `bulk_delete`, `attach`, `detach`, `publish`, `unpublish`.
`resource_type`	`string`	The type of resource that was affected (e.g. `interaction`, `object`, `workflow`).
`resource_id`	`string`	The ID of the affected resource.
`timestamp`	`string`	ISO 8601 timestamp of when the event occurred.
`request_id`	`string`	Unique identifier for the HTTP request that triggered the event.
`status`	`number`	HTTP status code of the response.
`success`	`boolean`	Whether the action completed successfully.
`principal_id`	`string \| null`	ID of the principal that performed the action (API key or service account).
`principal_type`	`string \| null`	Type of principal (e.g. `apikey`, `user`).
`principal_user_id`	`string \| null`	ID of the human user, if applicable.
`roles`	`string[]`	Roles assigned to the principal at the time of the event.
`account_id`	`string \| null`	Account ID.
`project_id`	`string \| null`	Project ID.
`tenant_id`	`string \| null`	Tenant ID.
`account_name`	`string \| null`	Human-readable account name.
`project_name`	`string \| null`	Human-readable project name.

Code Examples

List Audit Events

curl --location --request GET 'https://api.vertesia.io/api/v1/audit-trail?actions=create,update&from=2025-01-01T00:00:00Z&to=2025-01-31T23:59:59Z&limit=20' \
--header 'Authorization: Bearer <YOUR_JWT_TOKEN>'

Paginating Through Results

Use offset and the hasNext field to paginate through large result sets.

Pagination

import { VertesiaClient } from '@vertesia/client';

const client = new VertesiaClient({
  site: 'api.vertesia.io',
  apikey: '<YOUR_API_KEY>',
});

let offset = 0;
const limit = 50;
let hasMore = true;

while (hasMore) {
  const response = await client.auditTrail.list({
    actions: ['delete'],
    limit,
    offset,
  });

  for (const event of response.events) {
    console.log(`${event.timestamp} - ${event.action} ${event.resource_type}/${event.resource_id}`);
  }

  hasMore = response.hasNext;
  offset += limit;
}