> ## 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
> Um stream de eventos empresarial, em tempo real, de execuções de IA e atividade do workspace para governança, observabilidade, FinOps, analytics, conformidade e segurança.
Eventos de Auditoria é o stream de eventos empresarial da Tess AI. Ele expõe uma exportação normalizada e em tempo real das execuções de IA e da atividade do workspace, que qualquer plataforma empresarial pode consumir — SIEM, data lakes, ferramentas de governança, plataformas de FinOps, pipelines de analytics e fluxos personalizados.
Como a Tess é a camada de orquestração que fica à frente de todos os provedores de modelos, este stream carrega um contexto que os provedores individualmente não conseguem enxergar: qual workspace e usuário disparou a atividade, a qual execução de agente ou chamada de ferramenta ela pertence, qual modelo e provedor a atendeu, quanto tempo levou, quais políticas foram aplicadas e quanto do saldo de créditos do workspace foi consumido. Isso torna o stream valioso muito além da auditoria — ele é uma base para observabilidade empresarial, gestão de custos e analytics.
Eventos de Auditoria estão disponíveis apenas para **planos Enterprise**. O workspace precisa ter a funcionalidade de eventos de auditoria habilitada, e o token de API precisa ter permissão para ler eventos de auditoria do workspace selecionado.
## O que você pode construir
Um único stream habilita muitos casos de uso empresariais:
* **Monitoramento de segurança** — encaminhe eventos para o seu SIEM e crie alertas para atividades de alto risco.
* **Conformidade e auditoria** — mantenha um registro imutável de quem fez o quê, quando e sobre qual entidade.
* **Governança de IA** — alimente plataformas de governança que acompanham o uso de modelos e a aplicação de políticas nas execuções.
* **AI FinOps e análise de custos** — atribua o consumo de créditos e o volume de uso por workspace, usuário, modelo e provedor.
* **Chargeback e showback** — cobre ou reporte o consumo de créditos para as equipes que o geram.
* **Análise de uso** — entenda a adoção e o volume de execuções por agente e modelo.
* **Monitoramento operacional** — acompanhe latência, falhas e comportamento de chamadas de ferramentas nas execuções.
* **Ingestão em data lake** — armazene eventos brutos no seu data warehouse para análise de longo prazo.
* **Fluxos empresariais personalizados** — dispare automações a partir de qualquer tipo de evento.
## Consumidores suportados
O endpoint é uma exportação genérica, não um webhook exclusivo de segurança. Destinos comuns incluem:
| Categoria | Exemplos |
| ---------------------------- | ----------------------------------------------------------------- |
| SIEM | Splunk, Microsoft Sentinel, IBM QRadar |
| Data lakes e data warehouses | Databricks, Snowflake, BigQuery |
| Plataformas de governança | Microsoft Purview, Collibra, BigID, Immuta |
| Streaming e mensageria | Apache Kafka, Azure Event Hub, Google Pub/Sub |
| Armazenamento de objetos | Amazon S3, Azure Blob Storage, Google Cloud Storage (GCS) |
| FinOps e analytics | Plataformas de análise de custos, pipelines internos de analytics |
| Personalizado | Qualquer webhook ou coletor HTTPS |
## Arquitetura
A Tess emite um único stream de eventos empresarial via HTTPS que se distribui para as plataformas que a sua organização utiliza.
```text theme={null}
TESS
Enterprise Event Stream
│
HTTPS / Webhook
┌─────────────┬───┴────────┬──────────────┐
│ │ │ │
SIEM Data Lake Governança AI FinOps
│ │ │ │
Splunk Databricks MS Purview Custo por time
Sentinel Snowflake Collibra Chargeback
QRadar BigQuery BigID Showback
```
## Endpoint
```http theme={null}
GET https://api.tess.im/audit-events
```
Envie toda requisição com:
* `Authorization: Bearer YOUR_API_KEY`
* `Accept: application/json`
* `x-workspace-id: YOUR_WORKSPACE_ID`
A resposta sempre fica limitada ao workspace informado em `x-workspace-id`. Eventos que não pertencem de forma clara a um único workspace não são emitidos neste feed.
## Exemplo de requisição
```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 da janela de auditoria. Use um timestamp ISO-8601.
Fim da janela de auditoria. Deve ser maior ou igual a `from`. A janela não pode exceder 30 dias.
Número de eventos retornados. O padrão e `50`. O mínimo e `1`; o máximo e `200`.
Cursor opaco retornado em `page.next_cursor`. Envie esse valor para continuar a leitura a partir da página anterior.
Filtra pela origem. Os valores suportados são `auditable` e `activity`.
Filtra pelo tipo de evento normalizado, como `user_updated`, `workspace_created` ou `agent_execution_completed`.
Filtra pelo ID do usuário ator. Use `0` para eventos gerados pelo sistema.
Filtra pelo tipo da entidade, como `user`, `workspace`, `agent_execution` ou `agent_message`.
Filtra pelo ID da entidade.
Filtra pelo nível de risco. Os valores suportados são `low`, `medium`, `high` e `critical`.
## Resposta
```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"
}
}
```
## Schema do evento
Cada evento usa o mesmo formato normalizado:
* `id`: ID único do evento com prefixo da origem, como `activity:100001` ou `auditable:9001`.
* `occurred_at`: Timestamp UTC do evento.
* `workspace_id`: Workspace dono do evento.
* `source`: Categoria de origem do evento, atualmente `activity` ou `auditable`.
* `event_type`: Nome normalizado do evento.
* `action`: Ação canônica, como `created`, `updated`, `completed`, `failed` ou `blocked`.
* `actor`: Usuário ou sistema que causou o evento.
* `entity`: Objeto afetado pelo evento.
* `changes`: Detalhes estruturados da alteração, incluindo valores anteriores, novos valores e os campos alterados quando existe um diff disponível.
* `metadata`: Contexto adicional que ajuda a classificar, investigar ou correlacionar o evento.
* `risk_level`: `low`, `medium`, `high` ou `critical`.
* `schema_version`: Versão do schema normalizado do evento.
### Contexto de execução no metadata
Para eventos de execução de IA, o campo `metadata` carrega o contexto de orquestração que só a Tess consegue fornecer. Dependendo do tipo de evento, ele pode incluir:
* Identificadores de workspace e ator (usuário ou sistema)
* A entidade relacionada, como a execução de agente ou a mensagem de agente
* Modelo e provedor da ferramenta
* Latência (`duration_ms`)
* Detalhes da chamada de ferramenta (`tool_call_id`, `tool_name`, `tool_status`)
* Aplicação de políticas (`policy_name`, `policy_reason` e se a chamada foi bloqueada)
* Consumo de créditos (`amount`, `credit_operation`, `credit_bucket`) para cada incremento, decremento ou perda de crédito
* Status do resultado
É isso que torna o stream útil para analytics empresarial e gestão de custos de IA, não apenas para auditoria de segurança.
## AI FinOps
Como a Tess orquestra todas as execuções de IA, ela consegue exportar sinais de uso que os provedores de modelos não conseguem produzir por conta própria. Use o stream para impulsionar iniciativas de AI FinOps:
* **Consumo de créditos por workspace e usuário** — todo incremento, decremento ou perda no saldo de créditos de um workspace é um evento auditado, com `amount`, `credit_operation` e `credit_bucket`.
* **Volume de uso por modelo e provedor** — eventos de execução de agente e de chamada de ferramenta carregam `model` e `tool_provider`, permitindo detalhar o volume de execuções pelo que a sua organização realmente usa.
* **Chargeback e showback** — atribua o consumo de créditos ao workspace ou usuário que o gerou.
* **Sinais operacionais de custo** — `duration_ms` em execuções e chamadas de ferramentas mostra onde a latência, e portanto o tempo de computação, se concentra.
Armazene o stream no seu data warehouse (Snowflake, BigQuery, Databricks) ou plataforma de FinOps e agregue por esses campos de `metadata` para montar dashboards de consumo por workspace, usuário, modelo e provedor.
## Consumindo o stream
Use este endpoint como uma fonte pull a partir de qualquer coletor, pipeline ou plataforma.
Configuração recomendada:
1. Crie um token de API Enterprise dedicado para ingestão de eventos.
2. Armazene o token no gerenciador de segredos da sua plataforma.
3. Consulte `GET /audit-events` com uma janela curta, como 5 ou 15 minutos.
4. Guarde o último `next_cursor` bem-sucedido por workspace.
5. Preserve o JSON original no momento da ingestão.
6. Mapeie campos como `event_type`, `actor.id`, `entity.type`, `entity.id`, `risk_level` e `workspace_id` para o schema ou as propriedades customizadas da sua plataforma.
7. Crie alertas, ou agregações, para tipos de evento e campos de `metadata` de acordo com o seu caso de uso.
Use `id` e `occurred_at` para deduplicação e replay seguro.
### Exemplo: ingestão em SIEM
Para um SIEM como Splunk, Microsoft Sentinel ou IBM QRadar, trate o endpoint como uma fonte de logs JSON baseada em pull e crie alertas para tipos de evento de alto risco ou valores de `risk_level` de acordo com a política de segurança da sua organização.
Especificamente no IBM QRadar, configure a Tess AI como uma fonte de logs JSON customizada ou direcione a API por um coletor intermediário que encaminhe os eventos para o QRadar. Preserve o JSON normalizado e crie propriedades customizadas para:
* `workspace_id`
* `source`
* `event_type`
* `action`
* `actor.id`
* `actor.type`
* `entity.type`
* `entity.id`
* `risk_level`
* `id`
* `schema_version`
## Paginação
Leia os eventos em ordem crescente por `occurred_at` e ID do evento.
Se `page.has_more` for `true`, chame o endpoint novamente com os mesmos filtros e o valor retornado em `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'
```
## Erros
* `401` ou `403`: Token inválido, ausência do plano Enterprise, ausência da permissão de eventos de auditoria ou falta de acesso ao workspace.
* `422`: Parâmetros ausentes ou inválidos, `x-workspace-id` ausente, cursor inválido ou janela maior que 30 dias.
* `429`: Limite de requisições excedido.
* `503`: Uma das fontes de eventos de auditoria está temporariamente indisponível. Tente a mesma requisição novamente mais tarde.
### **Cabeçalhos**
ID do workspace. **Obrigatório a partir de 01/09/2026.** Até lá, se omitido, usa o workspace selecionado do usuário (deprecated). Após a data, ausência → **422**.