> ## 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. # Uso do workspace > Liste o histórico de execuções de agentes de um workspace com filtros, paginação e campos enriquecidos. 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** ```http cURL theme={null} curl --request GET \ --url 'https://api.tess.im/workspaces/usage?range=7d&page=1&per_page=20' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'x-workspace-id: YOUR_WORKSPACE_ID' \ --header 'Accept: application/json' \ --header 'x-workspace-id: YOUR_WORKSPACE_ID' ``` ```json Node.js theme={null} const axios = require('axios'); const config = { method: 'get', url: 'https://api.tess.im/workspaces/usage', params: { range: '7d', page: 1, per_page: 20 }, headers: { 'Authorization': 'Bearer YOUR_API_KEY', 'x-workspace-id': 'YOUR_WORKSPACE_ID', 'Accept': 'application/json', 'x-workspace-id': 'YOUR_WORKSPACE_ID' } }; try { const response = await axios(config); console.log(response.data); } catch (error) { console.error(error); } ``` ```python Python theme={null} import requests url = "https://api.tess.im/workspaces/usage" params = { "range": "7d", "page": 1, "per_page": 20 } headers = { "Authorization": "Bearer YOUR_API_KEY", "x-workspace-id": "YOUR_WORKSPACE_ID", "Accept": "application/json", "x-workspace-id": "YOUR_WORKSPACE_ID" } response = requests.get(url, params=params, headers=headers) print(response.json()) ``` ```php PHP theme={null} '7d', 'page' => 1, 'per_page' => 20 ]); curl_setopt_array($curl, [ CURLOPT_URL => "https://api.tess.im/workspaces/usage?" . $query, 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 YOUR_API_KEY", "x-workspace-id: YOUR_WORKSPACE_ID", "Accept: application/json", "x-workspace-id: YOUR_WORKSPACE_ID" ] ]); $response = curl_exec($curl); $err = curl_error($curl); curl_close($curl); if ($err) { echo "Error: " . $err; } else { echo $response; } ``` ```java Java theme={null} import java.net.URI; import java.net.http.HttpClient; import java.net.http.HttpRequest; import java.net.http.HttpResponse; HttpClient client = HttpClient.newHttpClient(); HttpRequest request = HttpRequest.newBuilder() .uri(URI.create("https://api.tess.im/workspaces/usage?range=7d&page=1&per_page=20")) .header("Authorization", "Bearer YOUR_API_KEY") .header("x-workspace-id", "YOUR_WORKSPACE_ID") .header("Accept", "application/json") .header("x-workspace-id", "YOUR_WORKSPACE_ID") .GET() .build(); HttpResponse response = client.send(request, HttpResponse.BodyHandlers.ofString()); System.out.println(response.body()); ``` ```go Go theme={null} package main import ( "fmt" "io/ioutil" "net/http" ) func main() { client := &http.Client{} req, err := http.NewRequest("GET", "https://api.tess.im/workspaces/usage?range=7d&page=1&per_page=20", nil) if err != nil { fmt.Println(err) return } req.Header.Add("Authorization", "Bearer YOUR_API_KEY") req.Header.Add("x-workspace-id", "YOUR_WORKSPACE_ID") req.Header.Add("Accept", "application/json") req.Header.Add("x-workspace-id", "YOUR_WORKSPACE_ID") resp, err := client.Do(req) if err != nil { fmt.Println(err) return } defer resp.Body.Close() body, err := ioutil.ReadAll(resp.Body) if err != nil { fmt.Println(err) return } fmt.Println(string(body)) } ``` ```jsonnet .NET theme={null} using System; using System.Net.Http; using System.Threading.Tasks; class Program { static async Task Main(string[] args) { using (var client = new HttpClient()) { client.DefaultRequestHeaders.Add("Authorization", "Bearer YOUR_API_KEY"); client.DefaultRequestHeaders.Add("x-workspace-id", "YOUR_WORKSPACE_ID"); client.DefaultRequestHeaders.Add("Accept", "application/json"); client.DefaultRequestHeaders.Add("x-workspace-id", "YOUR_WORKSPACE_ID"); try { var response = await client.GetAsync("https://api.tess.im/workspaces/usage?range=7d&page=1&per_page=20"); response.EnsureSuccessStatusCode(); string responseBody = await response.Content.ReadAsStringAsync(); Console.WriteLine(responseBody); } catch (HttpRequestException e) { Console.WriteLine("Exceção: " + e.Message); } } } } ``` ```ruby Ruby theme={null} require 'uri' require 'net/http' uri = URI('https://api.tess.im/workspaces/usage?range=7d&page=1&per_page=20') http = Net::HTTP.new(uri.host, uri.port) http.use_ssl = true request = Net::HTTP::Get.new(uri) request['Authorization'] = 'Bearer YOUR_API_KEY' request['x-workspace-id'] = 'YOUR_WORKSPACE_ID' request['Accept'] = 'application/json' request['x-workspace-id'] = 'YOUR_WORKSPACE_ID' response = http.request(request) puts response.read_body ``` ### **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**. ### **Parâmetros de consulta** 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. Início do intervalo (inclusivo). Obrigatório com end\_date. Fim do intervalo (inclusivo). Deve ser >= start\_date. Obrigatório com start\_date. O intervalo não pode ultrapassar 90 dias; senão 422. 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. Tipo de agente: all, chat, image, text, voiceover, video, code. all ou omitido = sem filtro de tipo. Número da página. Padrão 1, mínimo 1. 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** ```json theme={null} { "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", "execution_mode": "chat", "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** | **Campo** | **Descrição** | | :---------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | id | ID da execução ou id sintético como `chat-edited-{user_openai_id}` para chats editados. | | created\_at | Data/hora da execução. | | user\_id | Usuário que executou o agente. | | type | Tipo do agente (por exemplo `chat`, `image`, `text`, `voiceover`, `video`, `code`). | | status | `succeeded` ou `failed` (status diferentes de sucesso viram `failed`). | | email | E-mail do usuário que executou. | | credits | Créditos cobrados; **0** quando o status não é `succeeded`. | | name | Título do agente. | | slug | Slug do agente. | | output | **current:** 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\_id | Raiz da conversa (chat), quando existir. | | execution\_origin | Origem da execução nos metadados, quando houver. | | source | `current`, `archived` ou `edited`. | | used\_model | Nome do modelo quando disponível (`user_openai.used_model`, metadados da execução ou breakdown de usage pricing em execuções em modo agente); **`null`** para linhas **edited** ou quando nenhum modelo puder ser resolvido. | | tokens | Objeto `{ "input", "output", "total" }` quando há cobrança por token. Em chat normal, os valores vêm de `detailed_credits` com `metric == "token"`. Em execuções em **modo agente**, os valores vêm dos metadados da execução mesmo quando `detailed_credits` está zerado. **`null`** para image, video e voiceover (cobrança por execução, não por token). | | execution\_mode | **`agent`** para execuções em modo agente, **`chat`** para conversas normais, ou **`null`** para tipos que não são chat. Ajuda a distinguir orquestração agente de chat padrão ao revisar o consumo. | | link | URL 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** | **Status** | **Quando** | | :--------- | :--------------------------------------------------------------------------------------------------------------------------------------- | | 401 | Autenticação ausente ou inválida (Sanctum). | | 403 | Sem acesso ao workspace, ou **`user_id`** de outro usuário sem permissão para ver essas execuções. | | 422 | Parâ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.