> ## Documentation Index > Fetch the complete documentation index at: https://docs.zelto.ai/llms.txt > Use this file to discover all available pages before exploring further. # Agregar casos desde spans de trazas > Convierte spans LLM en casos de turno: la respuesta del span es la referencia. Copia contenido de llamadas al benchmark, que se conserva hasta que lo elimines. ## OpenAPI ````yaml /es/docs-openapi.json post /v1/benchmarks/{id}/cases/from-traces openapi: 3.1.0 info: title: API REST de Zelto version: v1 description: >- Acceso programático a tu organización de Zelto. Cada endpoint está limitado a la organización a la que pertenece la clave de API. Crea una clave en Configuración → Integraciones → Integración por API. servers: - url: https://api.zelto.ai description: Producción security: - bearerAuth: [] tags: - name: Monitors description: Exportaciones filtradas y asíncronas de resultados guardados de monitores. - name: Agentes description: >- Agentes de IA de voz y texto normalizados mediante el flujo de ingestión de Zelto. - name: Conversaciones description: >- Conversaciones de voz y texto (llamadas, chats y mensajes de voz), junto con sus transcripciones y grabaciones. - name: Métricas del cliente description: >- Evaluaciones proporcionadas por el cliente y asociadas a una conversación. Requiere que las métricas estén habilitadas. - name: Revisiones description: Estado de revisión humana de las conversaciones. - name: Colas de revisión description: Agrupa y dirige conversaciones para revisarlas por lotes. - name: Empresas description: Clientes o marcas para los que trabajan tus agentes, y sus logos. - name: Hallazgos description: >- Problemas estructurados descubiertos durante el análisis, con conversaciones y comentarios opcionales. - name: Experimentos description: >- Medición prospectiva de dos versiones de prompt enrutadas externamente mediante resultados de monitores independientes. - name: Organizaciones description: >- Aprovisionamiento de organizaciones sin interfaz. Requiere una clave de API de administrador o servicio. - name: Proveedores de IA description: >- Las claves propias de tu organización para proveedores de IA (trae tu propia clave). Los monitores pueden ejecutarse con ellas en lugar de los modelos integrados de Zelto. Solo propietarios o administradores; el secreto es de solo escritura. - name: Benchmarks description: >- Evaluaciones repetibles de prompts, modelos y motores de voz a texto de tus agentes sobre un conjunto fijo de casos, puntuadas por Judges. paths: /v1/benchmarks/{id}/cases/from-traces: post: tags: - Benchmarks summary: Agregar casos desde spans de trazas description: >- Convierte spans LLM en casos de turno: la respuesta del span es la referencia. Copia contenido de llamadas al benchmark, que se conserva hasta que lo elimines. operationId: createBenchmarkCasesFromTraces parameters: - name: id in: path required: true description: Id del benchmark. schema: type: string format: uuid - $ref: '#/components/parameters/BenchmarkIdempotencyKey' requestBody: required: true content: application/json: schema: type: object properties: items: minItems: 1 maxItems: 50 type: array items: type: object properties: traceId: type: string minLength: 1 maxLength: 200 spanId: type: string minLength: 1 maxLength: 200 description: El span LLM cuya respuesta prueba el caso. turns: default: span_messages description: >- Usar la transcripción de la llamada vinculada o los propios mensajes de entrada del span. type: string enum: - transcript - span_messages title: type: string minLength: 1 maxLength: 160 required: - traceId - spanId checkGroupId: default: null anyOf: - type: string format: uuid - type: 'null' tags: description: >- Etiquetas de usuario (máximo 20); se normalizan a minúsculas con guiones. maxItems: 20 type: array items: type: string maxLength: 200 draft: type: boolean default: false locale: description: >- Idioma de los títulos de caso generados y de las personas de llamante redactadas: `en-us` (predeterminado), `es` o `pt`. type: string enum: - en-us - es - pt required: - items responses: '201': description: Respuesta correcta. content: application/json: schema: $ref: '#/components/schemas/BenchmarkCaseBatchResult' headers: Idempotent-Replayed: description: >- `true` cuando esta respuesta repite una solicitud anterior con la misma Idempotency-Key. schema: type: string enum: - 'true' '400': $ref: '#/components/responses/ValidationFailed' '401': $ref: '#/components/responses/Unauthorized' '403': description: >- `plan_limit`: Esto superaría un límite de Benchmarks del plan de la organización. content: application/json: schema: $ref: '#/components/schemas/BenchmarkError' '404': $ref: '#/components/responses/NotFound' '409': description: >- `conflict`: El recurso no está en un estado que permita esto. `idempotency_key_reused`: Esta Idempotency-Key ya se usó para una solicitud distinta. content: application/json: schema: $ref: '#/components/schemas/BenchmarkError' components: parameters: BenchmarkIdempotencyKey: name: Idempotency-Key in: header required: false description: >- Clave opcional, única por organización (1-255 caracteres ASCII imprimibles, por ejemplo un UUID). Reenviar una solicitud con la misma clave devuelve el resultado original en lugar de crear otro; usarla para una solicitud distinta devuelve 409 `idempotency_key_reused`. schema: type: string minLength: 1 maxLength: 255 schemas: BenchmarkCaseBatchResult: type: object properties: cases: type: array items: $ref: '#/components/schemas/BenchmarkCase' skipped: type: array items: type: object properties: conversationId: type: string traceId: type: string reason: type: string required: - reason dryRun: type: boolean warning: type: string required: - cases description: >- Casos creados por una solicitud (o, con dryRun, los casos que se crearían). BenchmarkError: type: object required: - error - code - message properties: error: type: string enum: - validation_failed - invalid_parameter - approval_required - plan_limit - phi_mode_blocked - owner_required - not_entitled - forbidden - not_found - payload_too_large - estimate_stale - pointer_moved - no_draft_changes - conflict - idempotency_key_reused - rate_limited - model_unavailable description: Código de error estable (mismo valor que `code`). code: type: string enum: - validation_failed - invalid_parameter - approval_required - plan_limit - phi_mode_blocked - owner_required - not_entitled - forbidden - not_found - payload_too_large - estimate_stale - pointer_moved - no_draft_changes - conflict - idempotency_key_reused - rate_limited - model_unavailable description: Causa estable y legible por máquinas; compara con este campo. message: type: string description: Una frase en lenguaje claro que explica qué está mal. hint: type: string description: El siguiente paso que conviene probar. details: type: object additionalProperties: true description: >- Contexto propio de cada código, por ejemplo `approvalRequestId` con `approval_required` o `cap` con `plan_limit`. BenchmarkCase: type: object properties: id: type: string revision: type: integer type: type: string enum: - turn - conversation - audio title: type: string checkGroupId: type: - string - 'null' source: type: string enum: - production - trace - manual - red_team - api - mcp - upload sourceConversationId: type: - string - 'null' sourceAgent: anyOf: - $ref: '#/components/schemas/BenchmarkAgentRef' - type: 'null' sourceAgentVersionLabel: description: >- La versión del prompt del agente con la que se escribió el caso, por ejemplo "v7". type: string tags: type: array items: type: string language: type: - string - 'null' retired: type: boolean draft: type: boolean referenceUnverified: description: >- audio: la transcripción de referencia viene de la llamada y nadie la revisó todavía. El caso se ejecuta igual. type: boolean unpublished: type: boolean preview: type: string skippedJudgeIds: type: array items: type: string judgeParamOverrides: type: object propertyNames: type: string minLength: 1 maxLength: 100 additionalProperties: type: object propertyNames: type: string minLength: 1 maxLength: 100 additionalProperties: anyOf: - type: number - type: string maxLength: 500 addedInVersion: anyOf: - type: integer - type: 'null' retiredInVersion: anyOf: - type: integer - type: 'null' toolExpectation: $ref: '#/components/schemas/BenchmarkToolExpectation' replyExpectation: $ref: '#/components/schemas/BenchmarkReplyExpectation' traceSource: type: object properties: kind: type: string const: trace traceId: type: string spanId: type: - string - 'null' turns: type: string enum: - transcript - span_messages required: - kind - traceId - spanId - turns status: type: string enum: - ready - draft - preparing - failed contentPurged: type: boolean contentDeleted: description: >- "Eliminar todo el contenido de llamadas" vació este caso: el contenido y el razonamiento de los Judges ya no están, el título es un neutro "Caso N · contenido eliminado" y las puntuaciones se conservan. type: boolean createdAt: type: string description: Marca de tiempo ISO 8601. updatedAt: type: string description: Marca de tiempo ISO 8601. required: - id - revision - type - title - checkGroupId - source - sourceConversationId - sourceAgent - tags - language - retired - draft - preview description: 'Un caso: una entrada sobre la que se puntúa a los candidatos.' Error: type: object required: - error properties: error: type: string description: >- Nombre corto del error: `Unauthorized`, `Validation failed`, `Not found` o un código estable en snake_case que puedes comparar en tu código, como `unknown_query_parameter`, `invalid_parameter`, `payload_too_large` o `not_found`. message: type: string description: Una frase en lenguaje claro que explica qué falla y cómo corregirlo. code: type: string description: >- Causa estable y legible por máquina; compara con este valor y no con `error` ni `message`. En un 401: `missing_credentials`, `malformed_credentials`, `ingest_key_not_allowed` (se usó una clave de ingesta de observabilidad, solo de escritura, en un endpoint que requiere una clave API), `key_expired` o `invalid_credentials`. En otros casos, por ejemplo: `not_found`, `invalid_parameter`, `unknown_query_parameter`, `missing_parameter`, `validation_failed`, `invalid_json`, `payload_too_large`, `conversation_not_found`, `plan_required`. hint: type: string description: >- El siguiente paso a probar: dónde encontrar el id correcto, qué parámetros acepta el endpoint, cómo mejorar el plan o cómo autenticarte. parameter: type: string description: 'Con `invalid_parameter`: el parámetro de consulta rechazado.' unknown: type: array items: type: string description: >- Con `unknown_query_parameter`: los parámetros enviados que este endpoint no acepta. valid: type: array items: type: string description: >- Con `unknown_query_parameter`: los parámetros que acepta este endpoint. details: type: object additionalProperties: true BenchmarkAgentRef: type: object properties: id: type: string name: type: string required: - id - name description: Un agente al que está asignado el benchmark. BenchmarkToolExpectation: type: object properties: expect: type: string enum: - call - no_call - any calls: maxItems: 10 type: array items: type: object properties: tool: type: string minLength: 1 maxLength: 100 pattern: ^[A-Za-z0-9_.:-]+$ arguments: type: object propertyNames: type: string minLength: 1 maxLength: 100 additionalProperties: oneOf: - type: object properties: op: type: string const: equals value: {} required: - op - value - type: object properties: op: type: string const: one_of values: minItems: 1 maxItems: 50 type: array items: {} required: - op - values - type: object properties: op: type: string const: regex pattern: type: string minLength: 1 maxLength: 500 required: - op - pattern - type: object properties: op: type: string const: number_range min: type: number max: type: number required: - op - type: object properties: op: type: string const: present required: - op - type: object properties: op: type: string const: semantic description: type: string minLength: 1 maxLength: 500 required: - op - description - type: object properties: op: type: string const: ignore required: - op required: - tool - arguments ordered: type: boolean forbiddenTools: maxItems: 50 type: array items: type: string minLength: 1 maxLength: 100 pattern: ^[A-Za-z0-9_.:-]+$ noExtraArguments: type: boolean replyAt: type: integer minimum: 0 maximum: 10 required: - expect description: Qué llamada(s) a herramientas espera un caso de turno. BenchmarkReplyExpectation: type: object properties: check: type: string enum: - reference - different - none text: anyOf: - type: string maxLength: 20000 - type: 'null' idealReply: anyOf: - type: string maxLength: 20000 - type: 'null' required: - check description: Cómo se comprueba la respuesta hablada de un caso de turno. responses: ValidationFailed: description: >- El cuerpo o la cadena de consulta de la solicitud han fallado en la validación. `code` indica el tipo (`validation_failed`, `invalid_json`, `invalid_parameter`, `unknown_query_parameter`, `missing_parameter`) y un filtro con valores fijos lista los permitidos en `valid` (se comprueba cada valor repetido: `?status=open&status=zz` es un 400). Un cuerpo `validation_failed` incluye además `message` (los primeros campos que fallan), `hint` (cómo corregirlo, por ejemplo que la `description` de un hallazgo es un documento JSON de TipTap y no una cadena) y `details` (nombre del campo y mensajes). content: application/json: schema: $ref: '#/components/schemas/Error' Unauthorized: description: >- Clave API faltante o no válida. El cuerpo indica la causa en `code` (por ejemplo `ingest_key_not_allowed` cuando se usa aquí una clave de ingesta, solo de escritura), con un `message` y un `hint`. content: application/json: schema: $ref: '#/components/schemas/Error' NotFound: description: >- Recurso no encontrado en tu organización. También se devuelve cuando un id de la ruta no es un UUID, y `{ "error": "not_found" }` para una ruta que esta API no tiene. El cuerpo conserva `error: "Not found"` y añade `code: "not_found"` y un `hint`. content: application/json: schema: $ref: '#/components/schemas/Error' securitySchemes: bearerAuth: type: http scheme: bearer description: >- Envía `Authorization: Bearer YOUR_API_KEY`. La clave corresponde a una sola organización. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.