Spans

Un span es un paso dentro de una traza: la llamada al modelo, una búsqueda o una herramienta. Te dice en qué parte de la operación se fue el tiempo o apareció el error.

¿Qué es un span?

Cada span pertenece a una traza y puede colgar de otro span. Su tipo dice qué clase de paso fue:

Tipo	Para qué
`general`	Cualquier paso que no encaje en los demás. Es el tipo por defecto.
`llm`	Una llamada a un modelo de lenguaje, con su uso de tokens.
`retrieval`	Una búsqueda en una base de conocimiento (RAG).
`tool`	El uso de una herramienta (function calling).
`guardrail`	Una validación o control de seguridad sobre la entrada o la salida.

En la app

Cuando usas el chat o la inferencia de tu modelo, AstrApp agrega a cada traza un span de tipo llm con el modelo y los tokens usados. En las conversaciones que llegan por Kommo, registra un span por turno (ver Auto-tracing).

La app no tiene una pantalla de spans: los consultas por API.

API

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

GET/opik/spans

Lista los spans de una traza

POST/opik/spans

Crea un span

Listar los spans de una traza

Parámetro	Tipo	Descripción
`trace_id`	texto	Obligatorio. Id de la traza.
`type`	texto	Filtra por tipo de span.
`page`	número	Página, desde 1. Por defecto 1.
`size`	número	Spans por página. Por defecto 50.

bash

curl "https://app.astrapp.lat/api/v1/projects/$PROJECT_ID/opik/spans?trace_id=$TRACE_ID&type=llm" \
  -H "Authorization: Bearer sk_live_xxxxxxxxxxxxx"

Respuesta 200

{
  "success": true,
  "data": {
    "spans": [
      {
        "id": "…",
        "traceId": "…",
        "parentSpanId": null,
        "name": "llm-litellm",
        "type": "llm",
        "startTime": "2026-09-20T10:30:00.000Z",
        "endTime": "2026-09-20T10:30:01.800Z",
        "durationMs": 1800,
        "input": { "messages": [] },
        "output": { "content": "…" },
        "metadata": {},
        "tags": [],
        "model": "mi-modelo-v2",
        "usage": { "promptTokens": 150, "completionTokens": 80, "totalTokens": 230 },
        "hasError": false
      }
    ],
    "pagination": { "page": 1, "size": 50, "total": 1, "totalPages": 1 }
  }
}

Crear un span

Campo	Tipo	Descripción
`trace_id`	texto	Obligatorio. Id de la traza a la que pertenece.
`name`	texto	Obligatorio. Nombre del paso.
`type`	texto	Uno de los tipos de arriba. Por defecto general.
`parent_span_id`	texto	Id del span padre, para anidar pasos.
`input / output`	cualquiera	Entrada y salida del paso.
`model`	texto	Modelo usado, en spans de tipo llm.
`usage`	objeto	prompt_tokens, completion_tokens y total_tokens.
`metadata / tags`	objeto / texto[]	Datos y etiquetas libres.
`start_time / end_time`	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/spans" \
  -H "Authorization: Bearer sk_live_xxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "trace_id": "ID_DE_LA_TRAZA",
    "name": "respuesta-del-modelo",
    "type": "llm",
    "input": { "prompt": "Analiza este documento…" },
    "output": { "analysis": "…" },
    "model": "mi-modelo-v2",
    "usage": { "prompt_tokens": 500, "completion_tokens": 200, "total_tokens": 700 }
  }'

Respuesta 201

{
  "success": true,
  "data": {
    "span": {
      "id": "…",
      "traceId": "…",
      "name": "respuesta-del-modelo",
      "type": "llm",
      "createdAt": "2026-09-20T10:30:00.000Z"
    },
    "message": "Span creado exitosamente"
  }
}

Límites y notas

A diferencia de las trazas, aquí los campos van en snake_case: trace_id, start_time, end_time.
El filtro type se aplica sobre la página ya leída: una página puede traer menos de size spans.
Si Opik no responde, el listado devuelve spans: [] con un campo warning, y la creación responde 500.