> ## 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.
# Eventos de auditoria
> Un stream de eventos empresarial, en tiempo real, de ejecuciones de IA y actividad del workspace para gobernanza, observabilidad, FinOps, analitica, cumplimiento y seguridad.
Eventos de auditoria es el stream de eventos empresarial de Tess AI. Expone una exportacion normalizada y en tiempo real de las ejecuciones de IA y la actividad del workspace, que cualquier plataforma empresarial puede consumir: SIEM, data lakes, herramientas de gobernanza, plataformas de FinOps, pipelines de analitica y flujos personalizados.
Como Tess es la capa de orquestacion que se ubica frente a todos los proveedores de modelos, este stream transporta un contexto que los proveedores por si solos no pueden ver: que workspace y usuario genero la actividad, a que ejecucion de agente o llamada de herramienta pertenece, que modelo y proveedor la atendio, cuanto tardo, que politicas se aplicaron y cuanto del saldo de creditos del workspace consumio. Esto hace que el stream sea valioso mucho mas alla de la auditoria: es una base para observabilidad empresarial, gestion de costos y analitica.
Eventos de auditoria esta disponible solo para **planes Enterprise**. El workspace debe tener habilitada la función de eventos de auditoria, y el token de API debe tener permiso para leer eventos de auditoria del workspace seleccionado.
## Que puedes construir
Un unico stream habilita muchos casos de uso empresariales:
* **Monitoreo de seguridad** — reenvia eventos a tu SIEM y crea alertas para actividad de alto riesgo.
* **Cumplimiento y auditoria** — conserva un registro inmutable de quien hizo que, cuando y sobre que entidad.
* **Gobernanza de IA** — alimenta plataformas de gobernanza que rastrean el uso de modelos y la aplicacion de politicas en las ejecuciones.
* **AI FinOps y analisis de costos** — atribuye el consumo de creditos y el volumen de uso por workspace, usuario, modelo y proveedor.
* **Chargeback y showback** — cobra o reporta el consumo de creditos a los equipos que lo generan.
* **Analisis de uso** — comprende la adopcion y el volumen de ejecuciones por agente y modelo.
* **Monitoreo operativo** — rastrea latencia, fallos y comportamiento de llamadas a herramientas en las ejecuciones.
* **Ingestion en data lake** — almacena eventos en bruto en tu data warehouse para analisis a largo plazo.
* **Flujos empresariales personalizados** — dispara automatizaciones a partir de cualquier tipo de evento.
## Consumidores compatibles
El endpoint es una exportacion generica, no un webhook exclusivo de seguridad. Destinos comunes incluyen:
| Categoria | Ejemplos |
| ---------------------------- | ------------------------------------------------------------------ |
| SIEM | Splunk, Microsoft Sentinel, IBM QRadar |
| Data lakes y data warehouses | Databricks, Snowflake, BigQuery |
| Plataformas de gobernanza | Microsoft Purview, Collibra, BigID, Immuta |
| Streaming y mensajeria | Apache Kafka, Azure Event Hub, Google Pub/Sub |
| Almacenamiento de objetos | Amazon S3, Azure Blob Storage, Google Cloud Storage (GCS) |
| FinOps y analitica | Plataformas de analisis de costos, pipelines internos de analitica |
| Personalizado | Cualquier webhook o colector HTTPS |
## Arquitectura
Tess emite un unico stream de eventos empresarial via HTTPS que se distribuye a las plataformas que utiliza tu organizacion.
```text theme={null}
TESS
Enterprise Event Stream
│
HTTPS / Webhook
┌─────────────┬───┴────────┬──────────────┐
│ │ │ │
SIEM Data Lake Gobernanza AI FinOps
│ │ │ │
Splunk Databricks MS Purview Costo por equipo
Sentinel Snowflake Collibra Chargeback
QRadar BigQuery BigID Showback
```
## Endpoint
```http theme={null}
GET https://api.tess.im/audit-events
```
Envia cada solicitud con:
* `Authorization: Bearer YOUR_API_KEY`
* `Accept: application/json`
* `x-workspace-id: YOUR_WORKSPACE_ID`
La respuesta siempre esta limitada al workspace informado en `x-workspace-id`. Los eventos que no pertenecen claramente a un unico workspace no se emiten en este feed.
## Ejemplo de solicitud
```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'
```
## Parametros de consulta
Inicio de la ventana de auditoria. Usa un timestamp ISO-8601.
Fin de la ventana de auditoria. Debe ser mayor o igual que `from`. La ventana no puede exceder 30 dias.
Numero de eventos devueltos. El valor predeterminado es `50`. El minimo es `1`; el maximo es `200`.
Cursor opaco devuelto en `page.next_cursor`. Envialo para continuar leyendo desde la pagina anterior.
Filtra por origen. Los valores admitidos son `auditable` y `activity`.
Filtra por tipo de evento normalizado, como `user_updated`, `workspace_created` o `agent_execution_completed`.
Filtra por ID del usuario actor. Usa `0` para eventos generados por el sistema.
Filtra por tipo de entidad, como `user`, `workspace`, `agent_execution` o `agent_message`.
Filtra por ID de entidad.
Filtra por nivel de riesgo. Los valores admitidos son `low`, `medium`, `high` y `critical`.
## Respuesta
```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"
}
}
```
## Esquema del evento
Cada evento usa el mismo formato normalizado:
* `id`: ID unico del evento con prefijo de origen, como `activity:100001` o `auditable:9001`.
* `occurred_at`: Timestamp UTC del evento.
* `workspace_id`: Workspace propietario del evento.
* `source`: Categoria de origen del evento, actualmente `activity` o `auditable`.
* `event_type`: Nombre normalizado del evento.
* `action`: Acción canónica, como `created`, `updated`, `completed`, `failed` o `blocked`.
* `actor`: Usuario o sistema que causo el evento.
* `entity`: Objeto afectado por el evento.
* `changes`: Detalles estructurados del cambio, incluidos valores anteriores, nuevos valores y los campos modificados cuando hay un diff disponible.
* `metadata`: Contexto adicional que ayuda a clasificar, investigar o correlacionar el evento.
* `risk_level`: `low`, `medium`, `high` o `critical`.
* `schema_version`: Version del esquema normalizado del evento.
### Contexto de ejecucion en metadata
Para eventos de ejecucion de IA, el campo `metadata` transporta el contexto de orquestacion que solo Tess puede proporcionar. Segun el tipo de evento, puede incluir:
* Identificadores de workspace y actor (usuario o sistema)
* La entidad relacionada, como la ejecucion de agente o el mensaje de agente
* Modelo y proveedor de la herramienta
* Latencia (`duration_ms`)
* Detalles de la llamada a herramienta (`tool_call_id`, `tool_name`, `tool_status`)
* Aplicacion de politicas (`policy_name`, `policy_reason` y si la llamada fue bloqueada)
* Consumo de creditos (`amount`, `credit_operation`, `credit_bucket`) por cada incremento, decremento o perdida de credito
* Estado del resultado
Esto es lo que hace que el stream sea util para analitica empresarial y gestion de costos de IA, no solo para auditoria de seguridad.
## AI FinOps
Como Tess orquesta todas las ejecuciones de IA, puede exportar señales de uso que los proveedores de modelos no pueden producir por si solos. Usa el stream para impulsar iniciativas de AI FinOps:
* **Consumo de creditos por workspace y usuario** — cada incremento, decremento o perdida en el saldo de creditos de un workspace es un evento auditado, con `amount`, `credit_operation` y `credit_bucket`.
* **Volumen de uso por modelo y proveedor** — los eventos de ejecucion de agente y de llamada a herramienta transportan `model` y `tool_provider`, lo que permite desglosar el volumen de ejecuciones segun lo que tu organizacion realmente usa.
* **Chargeback y showback** — atribuye el consumo de creditos al workspace o usuario que lo genero.
* **Señales operativas de costo** — `duration_ms` en ejecuciones y llamadas a herramientas muestra donde se concentra la latencia, y por lo tanto el tiempo de computo.
Almacena el stream en tu data warehouse (Snowflake, BigQuery, Databricks) o plataforma de FinOps y agrega por estos campos de `metadata` para construir dashboards de consumo por workspace, usuario, modelo y proveedor.
## Consumir el stream
Usa este endpoint como una fuente pull desde cualquier colector, pipeline o plataforma.
Configuración recomendada:
1. Crea un token de API Enterprise dedicado para la ingestion de eventos.
2. Guarda el token en el gestor de secretos de tu plataforma.
3. Consulta `GET /audit-events` con una ventana corta, como 5 o 15 minutos.
4. Conserva el ultimo `next_cursor` exitoso por workspace.
5. Preserva el JSON original en el momento de la ingestión.
6. Mapea campos como `event_type`, `actor.id`, `entity.type`, `entity.id`, `risk_level` y `workspace_id` al esquema o las propiedades personalizadas de tu plataforma.
7. Crea alertas, o agregaciones, para tipos de evento y campos de `metadata` segun tu caso de uso.
Usa `id` y `occurred_at` para deduplicacion y replay seguro.
### Ejemplo: ingestion en SIEM
Para un SIEM como Splunk, Microsoft Sentinel o IBM QRadar, trata el endpoint como una fuente de logs JSON basada en pull y crea alertas para tipos de evento de alto riesgo o valores de `risk_level` segun la politica de seguridad de tu organizacion.
Especificamente en IBM QRadar, configura Tess AI como una fuente de logs JSON personalizada o enruta la API por un colector intermedio que reenvie eventos a QRadar. Conserva el JSON normalizado y crea propiedades personalizadas para:
* `workspace_id`
* `source`
* `event_type`
* `action`
* `actor.id`
* `actor.type`
* `entity.type`
* `entity.id`
* `risk_level`
* `id`
* `schema_version`
## Paginacion
Lee los eventos en orden ascendente por `occurred_at` e ID del evento.
Si `page.has_more` es `true`, llama al endpoint nuevamente con los mismos filtros y el valor devuelto en `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'
```
## Errores
* `401` o `403`: Token invalido, falta del plan Enterprise, falta del permiso de eventos de auditoria o sin acceso al workspace.
* `422`: Parametros ausentes o invalidos, `x-workspace-id` ausente, cursor invalido o ventana mayor que 30 dias.
* `429`: Limite de solicitudes excedido.
* `503`: Una de las fuentes de eventos de auditoria esta temporalmente no disponible. Intenta la misma solicitud mas tarde.
### **Encabezados**
ID del workspace. **Obligatorio a partir del 01/09/2026.** Hasta entonces, si se omite, se usa el workspace seleccionado del usuario (deprecated). Después de la fecha, ausencia → **422**.