> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mka1.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Auditoría de uso
> Rastrea el uso por usuario, correlaciona solicitudes en el borde de la API y estructura eventos de auditoría por unidad para la detección de uso indebido.
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 API](/es/api-reference/introduction) y abre el grupo **Usage**.
## Qué está disponible hoy
El borde de la API en vivo y la pila de observabilidad exponen los siguientes elementos:
* Las respuestas en vivo incluyen `X-Request-ID`.
* La configuración activa de Kong 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 dashboards `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
## 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.
```bash theme={null}
curl https://apigw.mka1.com/api/v1/llm/responses \
--request POST \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer ' \
--header 'X-On-Behalf-Of: ' \
--data '{
"model": "meetkai:functionary-pt",
"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.
```ts theme={null}
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 desde `X-On-Behalf-Of`.
Por ejemplo, la especificación activa actualmente expone endpoints de uso para respuestas, conversaciones, completions, embeddings, extract, classify y vector stores.
## 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`
```json theme={null}
{
"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 una política o guardarraíl se activa, regístralo en el mismo evento:
```json theme={null}
{
"action": "tool_call",
"outcome": "policy_violation",
"policy_action": "block"
}
```
## Detecta acciones indebidas
Agrupa tus logs y dashboards 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 una política?
El contrato de infraestructura activa actualmente define estos resultados:
* `success`
* `denied`
* `throttled`
* `validation_error`
* `policy_violation`
Los valores correspondientes de `policy_action` son:
* `warn`
* `block`
* `escalate`
Un ejemplo real 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 API.
2. Reduce al usuario final por `X-On-Behalf-Of` y `externalUserId`.
3. Usa `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 dashboards `MKLLM Gateway`, `Guardrail Dashboard` y `Sandbox Commands` para actividad de política o herramientas relacionada.
Esto te da un camino consistente desde el informe de uso hasta una solicitud específica y luego hasta el evento de acción exacto que fue permitido, advertido, bloqueado o escalado.