Saltar al contenido principal
GET
/
workspaces
/
usage
Uso del workspace
curl --request GET \
  --url https://api.tess.im/workspaces/usage \
  --header 'Authorization: Bearer <token>' \
  --header 'x-workspace-id: <x-workspace-id>'
Tu token de API debe poder usar agentes (use_agents), y debes tener acceso al workspace: mismas capas que el resto de rutas de agentes y archivos (autenticación Sanctum, comprobación de acceso al workspace).

​
Ejemplos 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'

​
Encabezados

​
x-workspace-id
integer
requerido
ID numérico del workspace. Valores inválidos o ausentes devuelven 422. Debes pertenecer a ese workspace; si no, 403.

​
Parámetros de consulta

​
range
string
Ventana relativa: 1d, 7d o 30d. Se ignora si se envían start_date y end_date. Si no se envía ninguna fecha, el valor efectivo por defecto es 30d.
​
start_date
date (YYYY-MM-DD)
Inicio del rango (inclusivo). Requerido con end_date.
​
end_date
date (YYYY-MM-DD)
Fin del rango (inclusivo). Debe ser >= start_date. Requerido con start_date. El rango no puede superar 90 días; si no, 422.
​
user_id
integer
Filtra por el usuario que ejecutó el agente. Sin permiso para ver la actividad de otros en el workspace, solo ves tus ejecuciones; filtrar por otro usuario devuelve 403.
​
type
string
Tipo de agente: all, chat, image, text, voiceover, video, code. all u omitido = sin filtro de tipo.
​
page
integer
Número de página. Predeterminado 1, mínimo 1.
​
per_page
integer
Tamaño de página. Predeterminado 20, entre 1 y 100.
Ventanas de fechas
  • Con start_date + end_date: el rango inclusivo tiene un máximo de 90 días.
  • Con range: la ventana es relativa al fin del día actual (1d = últimas 24 h desde ese instante; 7d / 30d = últimos 7 o 30 días naturales desde ese fin).
  • Si el flag usage_history_min_date está activo en la configuración, el inicio efectivo no será anterior a esa fecha (recorte silencioso).
Caché
  • El listado se guarda en caché unos 60 segundos por workspace, filtros y página. Las peticiones idénticas en ese intervalo pueden devolver el mismo cuerpo.

​
Respuesta

{
  "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": "Mi asistente personal",
      "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
  }
}
La paginación usa has_more: el servicio pide per_page + 1 filas; si existe la fila extra, has_more es true y solo las primeras per_page aparecen en items.

​
Campos de cada elemento

CampoDescripción
idID de ejecución o ID sintético como chat-edited-{user_openai_id} para chats editados.
created_atMarca de tiempo de la ejecución.
user_idUsuario que ejecutó el agente.
typeTipo de agente (por ejemplo chat, image, text, voiceover, video, code).
statussucceeded o failed (los estados distintos de éxito se mapean a failed).
emailCorreo del usuario que ejecutó.
creditsCréditos cobrados; 0 cuando el estado no es succeeded.
nameTítulo del agente.
slugSlug del agente.
outputcurrent: en image, video y voiceover es la salida real; en otros tipos, el texto fijo This content is only available on Tess. archived: This item was deleted. edited: This item was edited.
root_idRaíz de la conversación (chat), si existe.
execution_originOrigen en los metadatos de ejecución, si existe.
sourcecurrent, archived o edited.
used_modelNombre del modelo cuando está almacenado; null para filas edited en la lógica actual.
tokensObjeto { "input", "output", "total" } cuando detailed_credits indica facturación por token; si no, null (habitual en image, video, voiceover).
linkURL o ruta en la app para abrir el recurso cuando aplica; null en archived y edited y en tipos sin enlace. Chat (current): ruta /dashboard/user/ai/chat/ai-chat/{slug}?_chat_id={id} con root_id si está definido; si no, el id de la fila. Image / video / voiceover (current): URL firmada o pública en el almacenamiento cuando output sea utilizable; si no, null.

​
Errores

EstadoCuándo
401Autenticación ausente o inválida (Sanctum).
403Sin acceso al workspace, o user_id de otro usuario sin permiso para ver esas ejecuciones.
422Parámetros inválidos (validación Laravel), workspace inválido o ausente, fechas inválidas o rango personalizado mayor de 90 días.
Los errores de validación usan el payload estándar de Laravel; algunos errores de workspace devuelven JSON { "message": "..." } con mensaje traducible.