Saltar al contenido principal
Utiliza esta guía cuando necesites mostrar qué cuenta y usuario final realizó una solicitud, generar informes de uso por usuario e investigar acciones indebidas. La API de MKA1 te proporciona endpoints públicos de uso, encabezados de correlación de solicitudes en vivo y campos de observabilidad vinculados a usuarios. Para detalles de los endpoints, consulta la Referencia de la API y abre el grupo Usage.

​
Qué está disponible hoy

El borde de la API en vivo y la pila de observabilidad exponen las siguientes piezas:
  • Las respuestas en vivo incluyen X-Request-ID.
  • La configuración de Kong en vivo utiliza el plugin correlation-id con header_name: X-Request-ID, echo_downstream: true y generator: uuid#counter.
  • Los logs en vivo de SigNoz incluyen userId, externalUserId y userContext.
  • Los activos existentes de SigNoz incluyen los tableros MKLLM Gateway, Guardrail Dashboard y Sandbox Commands, además de las vistas de logs Sandbox Commands 24h, Sandbox Command Errors 24h y MKLLM Errors.
Ejemplos recientes de sistemas en vivo:
  • GET /api/v1/llm/responses devolvió X-Request-ID: 0736e48b-3d39-48d8-806c-952c907*****#12
  • GET /api/v1/agents devolvió X-Request-ID: 0736e48b-3d39-48d8-806c-952c90*****#13
  • Los agregados de 24 horas de SigNoz mostraron valores de externalUserId como docs-pt-br-user con 14 eventos y docs-test-user con 7 eventos
  • Los agregados de 24 horas de SigNoz mostraron valores de userId como dRdj8VeoyuE7P9txS7ZVQ8ixI2***** con 63 eventos y uy95pqlp4ABgWCn5oLikRGV1TT***** con 23 eventos

​
Cómo se ve esto en nuestro panel

vista de lista de SigNoz vista individual de log

​
Envía un ID de usuario final estable en cada solicitud delegada

Para integraciones de servidor con múltiples usuarios, envía tanto Authorization como X-On-Behalf-Of. Esto es lo que vincula el uso, los recursos y los logs con el usuario final correcto. 
curl https://apigw.mka1.com/api/v1/llm/responses \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <mka1-api-key>' \
  --header 'X-On-Behalf-Of: <end-user-id>' \
  --data '{
    "model": "gpt-5",
    "input": "Reply with ok."
  }'
Captura los encabezados de respuesta de esa solicitud y almacena X-Request-ID junto con la entrada de log de tu propia aplicación. Eso te da una clave de unión estable entre el borde de la API y la observabilidad aguas abajo.

​
Consulta informes de uso por usuario

Los endpoints públicos de uso soportan filtros user_ids y dimensiones group_by. Úsalos para informes a nivel de cuenta y luego utiliza los logs de SigNoz para investigar un usuario final o solicitud específica. 
import { SDK } from "@meetkai/mka1";

const mka1 = new SDK({
  bearerAuth: `Bearer ${process.env.MKA1_API_KEY}`,
});

const endTime = Math.floor(Date.now() / 1000);
const startTime = endTime - 24 * 60 * 60;

const usage = await mka1.llm.usage.responses({
  startTime,
  endTime,
  userIds: ["docs-test-user", "docs-pt-br-user"],
  groupBy: ["model", "background"],
});

console.log(usage);
Utiliza userIds para tus IDs de usuario final provenientes de X-On-Behalf-Of. Por ejemplo, la especificación en vivo actualmente expone endpoints de uso para respuestas, conversaciones, completions, embeddings, extract, classify y almacenes vectoriales.

​
Registra acciones como un vocabulario fijo de auditoría

La detección de uso indebido por usuario y por unidad depende de que tus servicios emitan eventos de acción consistentes. El contrato de auditoría compartido en infra-resources define los campos requeridos:
  • request_id
  • actor_id
  • unit_id
  • route_name
  • action
  • resource_type
  • resource_id
  • outcome
  • policy_action
{
  "request_id": "0736e48b-3d39-48d8-806c-952c907aa0be#12",
  "actor_id": "docs-test-user",
  "unit_id": "support-team-a",
  "route_name": "POST /api/v1/llm/responses",
  "action": "generate",
  "resource_type": "response",
  "resource_id": "resp_54d14e822fac430396ea2c04f771d7d3",
  "outcome": "success"
}
Si se activa una política o guardarraíl, regístralo en el mismo evento: 
{
  "action": "tool_call",
  "outcome": "policy_violation",
  "policy_action": "block"
}

​
Detecta acciones indebidas

Agrupa tus logs y tableros por actor_id, unit_id, action, outcome y policy_action. Esto te permite responder dos preguntas diferentes:
  • ¿Qué usuario final o unidad generó la actividad?
  • ¿Qué acciones fueron denegadas, limitadas o bloqueadas por política?
El contrato de infraestructura en vivo actualmente define estos resultados:
  • success
  • denied
  • throttled
  • validation_error
  • policy_violation
Los valores correspondientes de policy_action son:
  • warn
  • block
  • escalate
Un ejemplo en vivo ya visible en SigNoz el 30 de marzo de 2026 muestra la limitación en tiempo de ejecución de la actividad de herramientas en mkllm-gateway:
  • mensaje: Limiting parallel tool calls to respect max_tool_calls
  • requestedToolCalls: 2
  • allowedToolCalls: 1
  • maxToolCalls: 5
  • responseId: resp_bcc0e8bba9524e8d9c14289c0c6*****
Ese patrón es útil para la detección de acciones indebidas porque muestra la cantidad de acciones intentadas y la cantidad de acciones permitidas en el mismo evento.

​
Flujo práctico de investigación

Cuando investigues una solicitud sospechosa, sigue este orden:
  1. Comienza con el informe de uso a nivel de cuenta en los endpoints de uso de la Referencia de la API.
  2. Reduce al usuario final usando X-On-Behalf-Of y externalUserId.
  3. Utiliza X-Request-ID para correlacionar la solicitud exacta en el borde.
  4. Inspecciona los logs de SigNoz para userId, externalUserId, userContext, route_name, action y outcome.
  5. Revisa los tableros MKLLM Gateway, Guardrail Dashboard y Sandbox Commands para actividad de política o herramientas relacionada.
Esto te da un camino consistente desde el reporte de uso hasta una solicitud específica y luego hasta el evento de acción exacto que fue permitido, advertido, bloqueado o escalado.