Audit events

curl --request GET \
  --url https://api.tess.im/audit-events \
  --header 'Authorization: Bearer <token>' \
  --header 'x-workspace-id: <x-workspace-id>'

import requests

url = "https://api.tess.im/audit-events"

headers = {
    "x-workspace-id": "<x-workspace-id>",
    "Authorization": "Bearer <token>"
}

response = requests.get(url, headers=headers)

print(response.text)

const options = {
  method: 'GET',
  headers: {'x-workspace-id': '<x-workspace-id>', Authorization: 'Bearer <token>'}
};

fetch('https://api.tess.im/audit-events', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.tess.im/audit-events",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "x-workspace-id: <x-workspace-id>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.tess.im/audit-events"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("x-workspace-id", "<x-workspace-id>")
	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.get("https://api.tess.im/audit-events")
  .header("x-workspace-id", "<x-workspace-id>")
  .header("Authorization", "Bearer <token>")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.tess.im/audit-events")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["x-workspace-id"] = '<x-workspace-id>'
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

GET

audit-events

Audit events

curl --request GET \
  --url https://api.tess.im/audit-events \
  --header 'Authorization: Bearer <token>' \
  --header 'x-workspace-id: <x-workspace-id>'

import requests

url = "https://api.tess.im/audit-events"

headers = {
    "x-workspace-id": "<x-workspace-id>",
    "Authorization": "Bearer <token>"
}

response = requests.get(url, headers=headers)

print(response.text)

const options = {
  method: 'GET',
  headers: {'x-workspace-id': '<x-workspace-id>', Authorization: 'Bearer <token>'}
};

fetch('https://api.tess.im/audit-events', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.tess.im/audit-events",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "x-workspace-id: <x-workspace-id>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.tess.im/audit-events"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("x-workspace-id", "<x-workspace-id>")
	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.get("https://api.tess.im/audit-events")
  .header("x-workspace-id", "<x-workspace-id>")
  .header("Authorization", "Bearer <token>")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.tess.im/audit-events")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["x-workspace-id"] = '<x-workspace-id>'
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

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.

                          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

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 'x-workspace-id: YOUR_WORKSPACE_ID' \
  --header 'Accept: application/json' \
  --header 'x-workspace-id: YOUR_WORKSPACE_ID'

Query parameters

date-time

required

Start of the audit window. Use an ISO-8601 timestamp.

date-time

required

End of the audit window. It must be greater than or equal to from. The time window cannot exceed 30 days.

integer

Number of events to return. Default is 50. Minimum is 1; maximum is 200.

string

Opaque cursor returned in page.next_cursor. Send it to continue reading from the previous page.

string

Filter by source. Supported values are auditable and activity.

string

Filter by normalized event type, such as user_updated, workspace_created, or agent_execution_completed.

integer

Filter by actor user ID. Use 0 for system-generated events.

string

Filter by entity type, such as user, workspace, agent_execution, or agent_message.

string

Filter by entity ID.

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.

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:

Create an Enterprise API token dedicated to event ingestion.
Store the token in your platform’s secret manager.
Poll GET /audit-events with a narrow time window, such as 5 or 15 minutes.
Keep the last successful next_cursor per workspace.
Preserve the original JSON payload at ingestion time.
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.
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.

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

integer

required

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.

Import Template Pack

List Agent

⌘I

API Guide

API Reference

Integrations

Model Context Protocol (MCP)

Audit events

What you can build

Supported consumers

Architecture

Endpoint

Example request

Query parameters

Response

Event schema

Execution context in metadata

AI FinOps

Consuming the stream

Example: SIEM ingestion

Errors

Headers

​What you can build

​Supported consumers

​Architecture

​Endpoint

​Example request

​Query parameters

​Response

​Event schema

​Execution context in metadata

​AI FinOps

​Consuming the stream

​Example: SIEM ingestion

​Pagination

​Errors

​Headers

What you can build

Supported consumers

Architecture

Endpoint

Example request

Query parameters

Response

Event schema

Execution context in metadata

AI FinOps

Consuming the stream

Example: SIEM ingestion

Pagination

Errors

Headers