Skip to main content
GET
/
audit-events
Audit events
curl --request GET \
  --url https://api.tess.im/audit-events \
  --header 'Authorization: Bearer <token>'

Documentation Index

Fetch the complete documentation index at: https://docs.tess.im/llms.txt

Use this file to discover all available pages before exploring further.

The Audit Events API exposes a normalized feed of workspace activity for security monitoring, compliance review, and SIEM ingestion.
Audit Events is available only on Enterprise plans. Your workspace must have the SIEM audit events feature enabled, and your API token must be allowed to read audit events for the selected workspace.

​
Endpoint

GET https://api.tess.im/audit-events
Send every request with:
  • Authorization: Bearer YOUR_API_KEY
  • Accept: application/json
  • x-workspace-id: YOUR_WORKSPACE_ID
The response is always scoped to the workspace in x-workspace-id. Events that do not belong cleanly to one workspace are not emitted in this feed.

​
Example request

curl --request GET \
  --url 'https://api.tess.im/audit-events?from=2026-04-08T00:00:00Z&to=2026-04-09T00:00:00Z&limit=100' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Accept: application/json' \
  --header 'x-workspace-id: YOUR_WORKSPACE_ID'

​
Query parameters

​
from
date-time
required
Start of the audit window. Use an ISO-8601 timestamp.
​
to
date-time
required
End of the audit window. It must be greater than or equal to from. The time window cannot exceed 30 days.
​
limit
integer
Number of events to return. Default is 50. Minimum is 1; maximum is 200.
​
cursor
string
Opaque cursor returned in page.next_cursor. Send it to continue reading from the previous page.
​
source
string
Filter by source. Supported values are auditable and activity.
​
event_type
string
Filter by normalized event type, such as user_updated, workspace_created, or agent_execution_completed.
​
actor_id
integer
Filter by actor user ID. Use 0 for system-generated events.
​
entity_type
string
Filter by entity type, such as user, workspace, agent_execution, or agent_message.
​
entity_id
string
Filter by entity ID.
​
risk_level
string
Filter by risk level. Supported values are low, medium, high, and critical.

​
Response

{
  "data": [
    {
      "id": "activity:100001",
      "occurred_at": "2026-04-08T10:00:00Z",
      "workspace_id": 242,
      "source": "activity",
      "event_type": "agent_execution_completed",
      "action": "completed",
      "actor": {
        "id": 16643,
        "email": "user@example.com",
        "type": "user",
        "ip": null,
        "user_agent": null
      },
      "entity": {
        "type": "agent_execution",
        "id": "183450",
        "name": null
      },
      "changes": {
        "before": {},
        "after": {},
        "changed_fields": []
      },
      "metadata": {
        "workspace_id": 242,
        "actor_user_id": 16643,
        "status": "succeeded",
        "duration_ms": 1200
      },
      "risk_level": "low",
      "schema_version": 1
    }
  ],
  "page": {
    "next_cursor": null,
    "has_more": false
  },
  "meta": {
    "workspace_id": 242,
    "from": "2026-04-08T00:00:00Z",
    "to": "2026-04-09T00:00:00Z",
    "generated_at": "2026-04-09T00:00:02Z"
  }
}

​
Event schema

Each event uses the same normalized shape:
  • id: Unique event ID with the source prefix, such as activity:100001 or auditable:9001.
  • occurred_at: UTC timestamp for the event.
  • workspace_id: Workspace that owns the event.
  • source: Event source category, currently activity or auditable.
  • event_type: Normalized event name.
  • action: Canonical action, such as created, updated, completed, failed, or blocked.
  • actor: User or system principal that caused the event.
  • entity: Object affected by the event.
  • changes: Structured change details for the event, including previous values, new values, and the fields that changed when a diff is available.
  • metadata: Additional context that helps classify, investigate, or correlate the event.
  • risk_level: low, medium, high, or critical.
  • schema_version: Version of the normalized event schema.

​
Pagination

Read events in ascending order by occurred_at and event ID. If page.has_more is true, call the endpoint again with the same filters and the returned page.next_cursor. 
curl --request GET \
  --url 'https://api.tess.im/audit-events?from=2026-04-08T00:00:00Z&to=2026-04-09T00:00:00Z&limit=100&cursor=NEXT_CURSOR' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Accept: application/json' \
  --header 'x-workspace-id: YOUR_WORKSPACE_ID'

​
SIEM integration

Use this endpoint as a pull source from your SIEM or log collector. Recommended setup:
  1. Create an Enterprise API token dedicated to SIEM ingestion.
  2. Store the token in your SIEM secret manager.
  3. Poll GET /audit-events with a narrow time window, such as 5 or 15 minutes.
  4. Keep the last successful next_cursor per workspace.
  5. Preserve the original JSON payload at ingestion time.
  6. Map fields such as event_type, actor.id, entity.type, entity.id, risk_level, and workspace_id to SIEM custom properties.
  7. Alert on high-risk event types or risk_level values according to your security policy.

​
QRadar notes

For IBM QRadar, configure Tess AI as a custom JSON log source or route the API through an intermediate collector that forwards events to QRadar. Keep the normalized JSON intact and create custom properties for:
  • workspace_id
  • source
  • event_type
  • action
  • actor.id
  • actor.type
  • entity.type
  • entity.id
  • risk_level
  • id
  • schema_version
Use id and occurred_at for deduplication and replay safety.

​
Errors

  • 401 or 403: Invalid token, missing Enterprise entitlement, missing SIEM permission, or no access to the workspace.
  • 422: Missing or invalid parameters, missing x-workspace-id, invalid cursor, or a time window longer than 30 days.
  • 429: Rate limit exceeded.
  • 503: One of the audit event sources is temporarily unavailable. Retry the same request later.