Pular para o conteúdo principal
GET
/
workspaces
/
usage
Uso do workspace
curl --request GET \
  --url https://api.tess.im/workspaces/usage \
  --header 'Authorization: Bearer <token>' \
  --header 'x-workspace-id: <x-workspace-id>'
Seu token de API precisa poder usar agentes (use_agents), e você precisa ter acesso ao workspace—mesmas camadas dos outros endpoints de agentes e arquivos (autenticação Sanctum, checagem de acesso ao workspace).

​
Exemplos de código

curl --request GET \
  --url 'https://api.tess.im/workspaces/usage?range=7d&page=1&per_page=20' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Accept: application/json' \
  --header 'x-workspace-id: YOUR_WORKSPACE_ID'

​
Cabeçalhos

​
x-workspace-id
integer
obrigatório
ID numérico do workspace. Valores inválidos ou ausentes geram 422. Você precisa pertencer a esse workspace; caso contrário, 403.

​
Parâmetros de consulta

​
range
string
Janela relativa: 1d, 7d ou 30d. Ignorado se start_date e end_date forem enviados. Se nenhum parâmetro de data for enviado, o padrão efetivo é 30d.
​
start_date
date (AAAA-MM-DD)
Início do intervalo (inclusivo). Obrigatório com end_date.
​
end_date
date (AAAA-MM-DD)
Fim do intervalo (inclusivo). Deve ser >= start_date. Obrigatório com start_date. O intervalo não pode ultrapassar 90 dias; senão 422.
​
user_id
integer
Filtra pelo usuário que executou o agente. Sem permissão de leitura de atividade de outros no workspace, você vê só suas execuções; filtrar por outro usuário retorna 403.
​
type
string
Tipo de agente: all, chat, image, text, voiceover, video, code. all ou omitido = sem filtro de tipo.
​
page
integer
Número da página. Padrão 1, mínimo 1.
​
per_page
integer
Tamanho da página. Padrão 20, entre 1 e 100.
Janelas de data
  • Com start_date + end_date: o intervalo inclusivo tem teto de 90 dias.
  • Com range: a janela é relativa ao fim do dia atual (1d = últimas 24 h a partir desse instante; 7d / 30d = últimos 7 ou 30 dias corridos a partir desse fim).
  • Se o recurso usage_history_min_date estiver habilitado nas configurações, o início efetivo não fica antes dessa data (ajuste silencioso).
Cache
  • A listagem fica em cache por cerca de 60 segundos por workspace, filtros e página. Requisições idênticas nesse intervalo podem retornar o mesmo corpo.

​
Resposta

{
  "items": [
    {
      "id": "183450",
      "created_at": "2026-04-07 16:17:09",
      "user_id": 16643,
      "type": "chat",
      "status": "succeeded",
      "email": "user@example.com",
      "credits": 1.5,
      "name": "Meu assistente pessoal",
      "slug": "9b4994e3-07e9-4163-b5c0-9c4f18945eda-my-personal-assistant",
      "output": "This content is only available on Tess",
      "root_id": null,
      "execution_origin": "Platform",
      "source": "current",
      "used_model": "gpt-4o-mini",
      "tokens": {
        "input": 1240,
        "output": 320,
        "total": 1560
      },
      "link": "/dashboard/user/ai/chat/ai-chat/9b4994e3-07e9-4163-b5c0-9c4f18945eda-my-personal-assistant?_chat_id=183450"
    }
  ],
  "pagination": {
    "current_page": 1,
    "per_page": 20,
    "has_more": false
  }
}
A paginação usa has_more: o serviço busca per_page + 1 linhas; se a linha extra existir, has_more é true e só as primeiras per_page entram em items.

​
Campos de cada item

CampoDescrição
idID da execução ou id sintético como chat-edited-{user_openai_id} para chats editados.
created_atData/hora da execução.
user_idUsuário que executou o agente.
typeTipo do agente (por exemplo chat, image, text, voiceover, video, code).
statussucceeded ou failed (status diferentes de sucesso viram failed).
emailE-mail do usuário que executou.
creditsCréditos cobrados; 0 quando o status não é succeeded.
nameTítulo do agente.
slugSlug do agente.
outputcurrent: em image, video e voiceover é o output real; nos demais tipos, o texto fixo This content is only available on Tess. archived: This item was deleted. edited: This item was edited.
root_idRaiz da conversa (chat), quando existir.
execution_originOrigem da execução nos metadados, quando houver.
sourcecurrent, archived ou edited.
used_modelNome do modelo quando armazenado; null para linhas edited na lógica atual.
tokensObjeto { "input", "output", "total" } quando detailed_credits indica cobrança por token; senão null (comum em image, video, voiceover).
linkURL ou path no app para abrir o recurso quando aplicável; null em archived e edited e em tipos sem link. Chat (current): path /dashboard/user/ai/chat/ai-chat/{slug}?_chat_id={id} com root_id se definido, senão o id da linha. Image / video / voiceover (current): URL assinada ou pública no storage quando output for utilizável; senão null.

​
Erros

StatusQuando
401Autenticação ausente ou inválida (Sanctum).
403Sem acesso ao workspace, ou user_id de outro usuário sem permissão para ver essas execuções.
422Parâmetros inválidos (validação Laravel), workspace inválido ou ausente, datas inválidas ou intervalo customizado maior que 90 dias.
Erros de validação seguem o payload padrão do Laravel; alguns erros de workspace retornam JSON { "message": "..." } com mensagem traduzível.