Trazas

Una traza es el registro de una operación con tu modelo: qué entró, qué salió, cuánto tardó y con qué etiquetas. Es la unidad básica de Opik.

¿Qué es una traza?

Cada traza agrupa una operación completa. Sus pasos internos son spans.

Campo	Qué guarda
`id`	Identificador de la traza en Opik.
`name`	Nombre que le diste a la operación.
`startTime / endTime`	Inicio y fin en ISO 8601.
`durationMs`	Diferencia entre fin e inicio, en milisegundos.
`input / output`	Lo que entró y lo que salió, tal como lo mandaste.
`metadata`	Objeto libre: ids de conversación, modelo, canal…
`tags`	Etiquetas para filtrar.
`status`	`error` si `output.error` o `metadata.error` tienen valor; si no, `success`.
`model`	Sale de `metadata.model` o de `input.model`.
`tokensUsed`	Se llena si `output.usage` trae `prompt_tokens`, `completion_tokens` y `total_tokens`.

Los pasos de una traza (la llamada al modelo, una búsqueda, una herramienta) se registran como spans, y sus calificaciones como feedback.

En la app

AstrApp crea trazas por su cuenta cuando usas el chat, la inferencia de tus modelos y otras funciones; la lista está en Auto-tracing. Para registrar las llamadas de una aplicación tuya, usa la API de abajo.

La pantalla Entrenar › Trazas (Growth+) muestra las trazas del sistema de evaluación integrado de la app. Las trazas de Opik de esta página se consultan por API.

API

Rutas bajo /api/v1/projects/{projectId}. Funcionan con la sesión de la app o con API key.

GET/opik/traces

Lista las trazas

POST/opik/traces

Crea una traza

{projectId} tiene que ser el UUID de uno de tus proyectos: con otro valor la API responde 400.

Listar trazas

Parámetro	Tipo	Descripción
`page`	número	Página, desde 1. Por defecto 1.
`perPage`	número	Trazas por página, de 1 a 100. Por defecto 20.
`tags`	texto	Etiquetas separadas por coma.

bash

curl "https://app.astrapp.lat/api/v1/projects/$PROJECT_ID/opik/traces?perPage=20&tags=soporte" \
  -H "Authorization: Bearer sk_live_xxxxxxxxxxxxx"

Respuesta 200

{
  "success": true,
  "data": [
    {
      "id": "…",
      "name": "atencion-cliente",
      "startTime": "2026-09-20T10:30:00.000Z",
      "endTime": "2026-09-20T10:30:02.340Z",
      "durationMs": 2340,
      "input": { "message": "¿Cómo devuelvo un producto?" },
      "output": { "response": "Tienes 30 días para…" },
      "metadata": { "model": "mi-modelo-v2" },
      "tags": ["soporte"],
      "status": "success",
      "model": "mi-modelo-v2"
    }
  ],
  "pagination": { "total": 1, "page": 1, "per_page": 20, "total_pages": 1 }
}

Crear una traza

Campo	Tipo	Descripción
`name`	texto	Obligatorio. De 1 a 255 caracteres.
`input`	cualquiera	Entrada de la operación.
`output`	cualquiera	Salida de la operación.
`metadata`	objeto	Datos libres de la operación.
`tags`	texto[]	Hasta 20 etiquetas.
`startTime / endTime`	fecha	ISO 8601. Si faltan, se usa la hora de la petición.

bash

curl -X POST "https://app.astrapp.lat/api/v1/projects/$PROJECT_ID/opik/traces" \
  -H "Authorization: Bearer sk_live_xxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "atencion-cliente",
    "input": { "message": "¿Cómo devuelvo un producto?" },
    "output": {
      "response": "Tienes 30 días para…",
      "usage": { "prompt_tokens": 25, "completion_tokens": 20, "total_tokens": 45 }
    },
    "metadata": { "model": "mi-modelo-v2", "conversation_id": "conv-123" },
    "tags": ["soporte", "devoluciones"]
  }'

Responde 201 con la traza en data, con los mismos campos del listado. Guarda su id: lo necesitas para agregarle spans y feedback.

Límites y notas

500 peticiones por minuto a /opik/traces, sumando GET y POST. Con la sesión de la app se cuenta por usuario; con API key, por dirección IP. Al pasarte recibes 429 con los headers Retry-After y X-RateLimit-Remaining.
No hay endpoint para crear varias trazas en una petición: manda una por llamada.
En el listado, pagination.total cuenta solo las trazas de la página actual. Para recorrerlas todas, avanza page hasta recibir menos de perPage.
Si Opik no responde, el listado devuelve data: [].

Filtros que todavía no aplican

El listado acepta status, search, startDate y endDate, pero hoy no filtran el resultado. Filtra por tags o del lado de tu código.