> ## 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.
# Audit events
> A real-time enterprise event stream of AI execution and workspace activity for governance, observability, FinOps, analytics, compliance, and security.
Audit Events is the enterprise event stream for Tess AI. It exposes a normalized, real-time export of AI execution and workspace activity that any enterprise platform can consume — SIEM, data lakes, governance tools, FinOps platforms, analytics pipelines, and custom workflows.
Because Tess is the orchestration layer that sits in front of every model provider, this stream carries context that individual providers cannot see on their own: which workspace and user triggered the activity, which agent execution or tool call it belongs to, which model and provider served it, how long it took, which policies were enforced, and how much of the workspace's credit balance it consumed. That makes the stream valuable well beyond auditing — it is a foundation for enterprise observability, cost management, and analytics.
Audit Events is available only on **Enterprise plans**. Your workspace must have the audit events feature enabled, and your API token must be allowed to read audit events for the selected workspace.
## What you can build
A single stream powers many enterprise use cases:
* **Security monitoring** — forward events to your SIEM and alert on high-risk activity.
* **Compliance and audit** — retain an immutable record of who did what, when, and to which entity.
* **AI governance** — feed governance platforms that track model usage and policy enforcement across executions.
* **AI FinOps and cost analytics** — attribute credit consumption and usage volume by workspace, user, model, and provider.
* **Chargeback and showback** — bill or report credit consumption back to the teams that generate it.
* **Usage analytics** — understand adoption and execution volume by agent and model.
* **Operational monitoring** — track latency, failures, and tool-call behavior across executions.
* **Data lake ingestion** — land raw events in your warehouse for long-term analysis.
* **Custom enterprise workflows** — trigger downstream automation from any event type.
## Supported consumers
The endpoint is a generic export, not a security-only webhook. Common destinations include:
| Category | Examples |
| ------------------------- | --------------------------------------------------------- |
| SIEM | Splunk, Microsoft Sentinel, IBM QRadar |
| Data lakes and warehouses | Databricks, Snowflake, BigQuery |
| Governance platforms | Microsoft Purview, Collibra, BigID, Immuta |
| Streaming and messaging | Apache Kafka, Azure Event Hub, Google Pub/Sub |
| Object storage | Amazon S3, Azure Blob Storage, Google Cloud Storage (GCS) |
| FinOps and analytics | Cost analytics platforms, internal analytics pipelines |
| Custom | Any HTTPS webhook or collector |
## Architecture
Tess emits a single enterprise event stream over HTTPS that fans out to whatever platforms your organization runs.
```text theme={null}
TESS
Enterprise Event Stream
│
HTTPS / Webhook
┌─────────────┬───┴────────┬──────────────┐
│ │ │ │
SIEM Data Lake Governance AI FinOps
│ │ │ │
Splunk Databricks MS Purview Cost per team
Sentinel Snowflake Collibra Chargeback
QRadar BigQuery BigID Showback
```
## Endpoint
```http theme={null}
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
```bash theme={null}
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 'x-workspace-id: YOUR_WORKSPACE_ID' \
--header 'Accept: application/json' \
--header 'x-workspace-id: YOUR_WORKSPACE_ID'
```
## Query parameters
Start of the audit window. Use an ISO-8601 timestamp.
End of the audit window. It must be greater than or equal to `from`. The time window cannot exceed 30 days.
Number of events to return. Default is `50`. Minimum is `1`; maximum is `200`.
Opaque cursor returned in `page.next_cursor`. Send it to continue reading from the previous page.
Filter by source. Supported values are `auditable` and `activity`.
Filter by normalized event type, such as `user_updated`, `workspace_created`, or `agent_execution_completed`.
Filter by actor user ID. Use `0` for system-generated events.
Filter by entity type, such as `user`, `workspace`, `agent_execution`, or `agent_message`.
Filter by entity ID.
Filter by risk level. Supported values are `low`, `medium`, `high`, and `critical`.
## Response
```json theme={null}
{
"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.
### Execution context in metadata
For AI execution events, `metadata` carries the orchestration context that only Tess can provide. Depending on the event type, it may include:
* Workspace and actor (user or system) identifiers
* The related entity, such as the agent execution or agent message
* Model and tool provider
* Latency (`duration_ms`)
* Tool call details (`tool_call_id`, `tool_name`, `tool_status`)
* Policy enforcement (`policy_name`, `policy_reason`, and whether the call was blocked)
* Credit consumption (`amount`, `credit_operation`, `credit_bucket`) for every credit increment, decrement, or loss
* Result status
This is what makes the stream useful for enterprise analytics and AI cost management, not just security auditing.
## AI FinOps
Because Tess orchestrates every AI execution, it can export usage signals that individual model providers cannot produce on their own. Use the stream to power AI FinOps initiatives:
* **Credit consumption per workspace and user** — every increment, decrement, and loss against a workspace's credit balance is an audited event carrying `amount`, `credit_operation`, and `credit_bucket`.
* **Usage volume by model and provider** — agent execution and tool-call events carry `model` and `tool_provider`, so you can break down execution volume by what your organization actually uses.
* **Chargeback and showback** — attribute credit consumption back to the workspace or user that generated it.
* **Operational cost signals** — `duration_ms` on executions and tool calls shows where latency, and therefore compute time, concentrates.
Land the stream in your warehouse (Snowflake, BigQuery, Databricks) or FinOps platform and aggregate on these `metadata` fields to build consumption dashboards per workspace, user, model, and provider.
## Consuming the stream
Use this endpoint as a pull source from any collector, pipeline, or platform.
Recommended setup:
1. Create an Enterprise API token dedicated to event ingestion.
2. Store the token in your platform's 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 your platform's schema or custom properties.
7. Alert on, or aggregate, event types and `metadata` fields according to your use case.
Use `id` and `occurred_at` for deduplication and replay safety.
### Example: SIEM ingestion
For a SIEM such as Splunk, Microsoft Sentinel, or IBM QRadar, treat the endpoint as a pull-based JSON log source and alert on high-risk event types or `risk_level` values according to your security policy.
For IBM QRadar specifically, 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`
## 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`.
```bash theme={null}
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 'x-workspace-id: YOUR_WORKSPACE_ID' \
--header 'Accept: application/json' \
--header 'x-workspace-id: YOUR_WORKSPACE_ID'
```
## Errors
* `401` or `403`: Invalid token, missing Enterprise entitlement, missing audit events 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.
### **Headers**
Workspace ID. **Required as of 2026-09-01.** Until then, if omitted, the user's selected workspace is used (deprecated). After the cutoff, a missing header returns **422**.