Niucore

Referencia

Analíticas

Métricas de uso, actividad y consumo de tokens.

Resumen de actividad

GETapi.niucore.com/api/v1/analytics/summary

Scope: analytics:read

Interacciones, usuarios y promedio por día dentro del rango. Sin rango, los últimos siete días.

No se pagina

Devuelve la serie completa del rango pedido. meta trae solo request_id —sin page, size ni total— y los parámetros de paginación se ignoran. Lo que acota el resultado es start_date/end_date, que por defecto cubren los últimos 7 días.

Credenciales acotadas a bibliotecas

Si la credencial está restringida a bibliotecas concretas, library_id es obligatorio y tiene que estar en su lista. Sin él la respuesta sería el total de la empresa, que incluye lo que la credencial no puede ver: la API lo pide en vez de recortar en silencio.

Consulta

start_datestring

Inicio del rango, YYYY-MM-DD. Va junto con end_date: mandar uno solo devuelve 422. Sin ninguno de los dos, la métrica cubre los últimos 7 días.

end_datestring

Fin del rango, YYYY-MM-DD, inclusive. Va junto con start_date.

library_idinteger

Acota la métrica a una biblioteca. Obligatorio si la credencial está limitada a bibliotecas concretas.

Devuelve

daystring

Fecha, YYYY-MM-DD.

total_interactionsinteger

Turnos de ese día.

total_usersinteger

Usuarios que conversaron.

averagenumber

Interacciones por usuario.

Errores

  • 403api_v1_resource_not_allowedFalta library_id en una credencial acotada, o el que se mandó está fuera de su lista. data.required_query_param lo dice.
curl -sS -X GET 'https://api.niucore.com/api/v1/analytics/summary?start_date=2026-08-01&end_date=2026-08-31' \
  -H "Authorization: Bearer $NIUCORE_ACCESS_TOKEN"
Respuesta
{
  "status": "success",
  "message": "Operación exitosa",
  "message_code": "api_v1_ok",
  "data": [
    {
      "day": "2026-08-01",
      "total_interactions": 184,
      "total_users": 21,
      "average": 8.76
    },
    {
      "day": "2026-08-02",
      "total_interactions": 96,
      "total_users": 12,
      "average": 8
    }
  ],
  "meta": {
    "request_id": "9f1c0a3e-7b2d-4f18-9a55-2c6e0d1b4a77"
  }
}

Actividad de usuarios

GETapi.niucore.com/api/v1/analytics/users-activity

Scope: analytics:read

Por cada día del rango: cuántos usuarios había, cuántos conversaron y cuántos no.

No se pagina

Devuelve la serie completa del rango pedido. meta trae solo request_id —sin page, size ni total— y los parámetros de paginación se ignoran. Lo que acota el resultado es start_date/end_date, que por defecto cubren los últimos 7 días.

Credenciales acotadas a bibliotecas

Si la credencial está restringida a bibliotecas concretas, library_id es obligatorio y tiene que estar en su lista. Sin él la respuesta sería el total de la empresa, que incluye lo que la credencial no puede ver: la API lo pide en vez de recortar en silencio.

Consulta

start_datestring

Inicio del rango, YYYY-MM-DD. Va junto con end_date: mandar uno solo devuelve 422. Sin ninguno de los dos, la métrica cubre los últimos 7 días.

end_datestring

Fin del rango, YYYY-MM-DD, inclusive. Va junto con start_date.

library_idinteger

Acota la métrica a una biblioteca. Obligatorio si la credencial está limitada a bibliotecas concretas.

Devuelve

daystring

Fecha, YYYY-MM-DD.

total_usersinteger

Usuarios acumulados hasta ese día.

active_usersinteger

Conversaron.

inactive_usersinteger

No conversaron.

total_interactionsinteger

Turnos del día.

averagenumber

Turnos por usuario activo.

curl -sS -X GET 'https://api.niucore.com/api/v1/analytics/users-activity?start_date=2026-08-01&end_date=2026-08-31' \
  -H "Authorization: Bearer $NIUCORE_ACCESS_TOKEN"
Respuesta
{
  "status": "success",
  "message": "Operación exitosa",
  "message_code": "api_v1_ok",
  "data": [
    {
      "day": "2026-08-01",
      "total_users": 37,
      "active_users": 21,
      "inactive_users": 16,
      "total_interactions": 184,
      "average": 8.76
    }
  ],
  "meta": {
    "request_id": "9f1c0a3e-7b2d-4f18-9a55-2c6e0d1b4a77"
  }
}

Interacciones por día

GETapi.niucore.com/api/v1/analytics/interactions-by-weekday

Scope: analytics:read

Turnos por día del rango, con el nombre del día de la semana.

No se pagina

Devuelve la serie completa del rango pedido. meta trae solo request_id —sin page, size ni total— y los parámetros de paginación se ignoran. Lo que acota el resultado es start_date/end_date, que por defecto cubren los últimos 7 días.

Credenciales acotadas a bibliotecas

Si la credencial está restringida a bibliotecas concretas, library_id es obligatorio y tiene que estar en su lista. Sin él la respuesta sería el total de la empresa, que incluye lo que la credencial no puede ver: la API lo pide en vez de recortar en silencio.

Consulta

start_datestring

Inicio del rango, YYYY-MM-DD. Va junto con end_date: mandar uno solo devuelve 422. Sin ninguno de los dos, la métrica cubre los últimos 7 días.

end_datestring

Fin del rango, YYYY-MM-DD, inclusive. Va junto con start_date.

library_idinteger

Acota la métrica a una biblioteca. Obligatorio si la credencial está limitada a bibliotecas concretas.

Devuelve

daystring

Nombre del día de la semana.

datestring

Fecha, YYYY-MM-DD.

totalinteger

Turnos de ese día.

total_usersinteger

Usuarios distintos que interactuaron ese día.

curl -sS -X GET 'https://api.niucore.com/api/v1/analytics/interactions-by-weekday' \
  -H "Authorization: Bearer $NIUCORE_ACCESS_TOKEN"
Respuesta
{
  "status": "success",
  "message": "Operación exitosa",
  "message_code": "api_v1_ok",
  "data": [
    {
      "day": "Lunes",
      "date": "2026-08-03",
      "total": 92,
      "total_users": 14
    },
    {
      "day": "Martes",
      "date": "2026-08-04",
      "total": 87,
      "total_users": 12
    }
  ],
  "meta": {
    "request_id": "9f1c0a3e-7b2d-4f18-9a55-2c6e0d1b4a77"
  }
}

Preguntas frecuentes

GETapi.niucore.com/api/v1/analytics/top-questions

Scope: analytics:read

Los temas más consultados del período, agrupados por tópico.

No se pagina

Devuelve la serie completa del rango pedido. meta trae solo request_id —sin page, size ni total— y los parámetros de paginación se ignoran. Lo que acota el resultado es start_date/end_date, que por defecto cubren los últimos 7 días.

Credenciales acotadas a bibliotecas

Si la credencial está restringida a bibliotecas concretas, library_id es obligatorio y tiene que estar en su lista. Sin él la respuesta sería el total de la empresa, que incluye lo que la credencial no puede ver: la API lo pide en vez de recortar en silencio.

Consulta

start_datestring

Inicio del rango, YYYY-MM-DD. Va junto con end_date: mandar uno solo devuelve 422. Sin ninguno de los dos, la métrica cubre los últimos 7 días.

end_datestring

Fin del rango, YYYY-MM-DD, inclusive. Va junto con start_date.

library_idinteger

Acota la métrica a una biblioteca. Obligatorio si la credencial está limitada a bibliotecas concretas.

Devuelve

topicstring

El tema.

labelsstring[]

Las fechas del rango, YYYY-MM-DD, una por día.

datanumber[]

Consultas de ese tema por día, alineado con labels.

curl -sS -X GET 'https://api.niucore.com/api/v1/analytics/top-questions?start_date=2026-09-01&end_date=2026-09-03' \
  -H "Authorization: Bearer $NIUCORE_ACCESS_TOKEN"
Respuesta
{
  "status": "success",
  "message": "Operación exitosa",
  "message_code": "api_v1_ok",
  "data": [
    {
      "topic": "Devoluciones",
      "labels": [
        "2026-09-01",
        "2026-09-02",
        "2026-09-03"
      ],
      "data": [
        12,
        9,
        17
      ]
    }
  ],
  "meta": {
    "request_id": "9f1c0a3e-7b2d-4f18-9a55-2c6e0d1b4a77"
  }
}

Interacciones por biblioteca

GETapi.niucore.com/api/v1/analytics/interactions-by-library

Scope: analytics:read

Cuánto se consultó cada biblioteca.

No se pagina

Devuelve la serie completa del rango pedido. meta trae solo request_id —sin page, size ni total— y los parámetros de paginación se ignoran. Lo que acota el resultado es start_date/end_date, que por defecto cubren los últimos 7 días.

Credenciales acotadas a bibliotecas

Si la credencial está restringida a bibliotecas concretas, library_id es obligatorio y tiene que estar en su lista. Sin él la respuesta sería el total de la empresa, que incluye lo que la credencial no puede ver: la API lo pide en vez de recortar en silencio.

Consulta

start_datestring

Inicio del rango, YYYY-MM-DD. Va junto con end_date: mandar uno solo devuelve 422. Sin ninguno de los dos, la métrica cubre los últimos 7 días.

end_datestring

Fin del rango, YYYY-MM-DD, inclusive. Va junto con start_date.

library_idinteger

Acota la métrica a una biblioteca. Obligatorio si la credencial está limitada a bibliotecas concretas.

Devuelve

workspacestring

Nombre de la biblioteca.

totalinteger

Interacciones.

curl -sS -X GET 'https://api.niucore.com/api/v1/analytics/interactions-by-library' \
  -H "Authorization: Bearer $NIUCORE_ACCESS_TOKEN"
Respuesta
{
  "status": "success",
  "message": "Operación exitosa",
  "message_code": "api_v1_ok",
  "data": [
    {
      "workspace": "Procedimientos de soporte",
      "total": 1204
    }
  ],
  "meta": {
    "request_id": "9f1c0a3e-7b2d-4f18-9a55-2c6e0d1b4a77"
  }
}

Archivos por biblioteca

GETapi.niucore.com/api/v1/analytics/files-by-library

Scope: analytics:read

Conteo de archivos por biblioteca. Es el único endpoint de métricas que no pide library_id en credenciales acotadas: se listan las permitidas y nada más.

No se pagina

Devuelve la serie completa del rango pedido. meta trae solo request_id —sin page, size ni total— y los parámetros de paginación se ignoran. Lo que acota el resultado es start_date/end_date, que por defecto cubren los últimos 7 días.

Devuelve

library_idinteger

Identificador.

namestring

Nombre.

filesinteger

Archivos vigentes.

curl -sS -X GET 'https://api.niucore.com/api/v1/analytics/files-by-library' \
  -H "Authorization: Bearer $NIUCORE_ACCESS_TOKEN"
Respuesta
{
  "status": "success",
  "message": "Operación exitosa",
  "message_code": "api_v1_ok",
  "data": [
    {
      "library_id": 31,
      "name": "Procedimientos de soporte",
      "files": 84
    }
  ],
  "meta": {
    "request_id": "9f1c0a3e-7b2d-4f18-9a55-2c6e0d1b4a77"
  }
}

Consumo por modelo

GETapi.niucore.com/api/v1/analytics/token-usage/by-model

Scope: analytics:read

Tokens consumidos, desglosados por modelo y proveedor.

No se pagina

Devuelve la serie completa del rango pedido. meta trae solo request_id —sin page, size ni total— y los parámetros de paginación se ignoran. Lo que acota el resultado es start_date/end_date, que por defecto cubren los últimos 7 días.

Qué abarca el total

Devuelve el consumo de toda la empresa solo si la credencial no está limitada a bibliotecas concretas y el usuario tiene metrics.read.all. En cualquier otro caso, el total es el del usuario en cuyo nombre actúa la credencial — nunca más de lo que esa persona ya puede consultar.

Atención

Estos dos endpoints solo miran start_date y end_date. library_id se acepta por uniformidad con el resto de las métricas, pero se ignora.

Consulta

start_datestring

Inicio del rango, YYYY-MM-DD. Va junto con end_date: mandar uno solo devuelve 422. Sin ninguno de los dos, la métrica cubre los últimos 7 días.

end_datestring

Fin del rango, YYYY-MM-DD, inclusive. Va junto con start_date.

Devuelve

model_namestring

Modelo.

provider_namestring

Proveedor.

is_autoboolean

Turnos resueltos por el balanceador. Con true, auto_breakdown trae qué modelo respondió cada uno.

message_countinteger

Turnos.

input_tokensinteger

Tokens de entrada.

output_tokensinteger

Tokens de salida.

total_tokensinteger

Total.

cache_read_tokensinteger

Tokens leídos de caché. No están incluidos en input_tokens.

cache_creation_tokensinteger

Tokens escritos a caché.

curl -sS -X GET 'https://api.niucore.com/api/v1/analytics/token-usage/by-model?start_date=2026-08-01&end_date=2026-08-31' \
  -H "Authorization: Bearer $NIUCORE_ACCESS_TOKEN"
Respuesta
{
  "status": "success",
  "message": "Operación exitosa",
  "message_code": "api_v1_ok",
  "data": [
    {
      "model_name": "gpt-4o",
      "provider_name": "OpenAI",
      "is_auto": false,
      "message_count": 1840,
      "input_tokens": 4210882,
      "output_tokens": 388104,
      "total_tokens": 4598986,
      "cache_read_tokens": 902144,
      "cache_creation_tokens": 41220
    }
  ],
  "meta": {
    "request_id": "9f1c0a3e-7b2d-4f18-9a55-2c6e0d1b4a77"
  }
}

Consumo agregado

GETapi.niucore.com/api/v1/analytics/token-usage/by-day

Scope: analytics:read

Los totales del rango, en un solo objeto —no una serie por día—.

No se pagina

Devuelve la serie completa del rango pedido. meta trae solo request_id —sin page, size ni total— y los parámetros de paginación se ignoran. Lo que acota el resultado es start_date/end_date, que por defecto cubren los últimos 7 días.

Qué abarca el total

Devuelve el consumo de toda la empresa solo si la credencial no está limitada a bibliotecas concretas y el usuario tiene metrics.read.all. En cualquier otro caso, el total es el del usuario en cuyo nombre actúa la credencial — nunca más de lo que esa persona ya puede consultar.

Atención

Estos dos endpoints solo miran start_date y end_date. library_id se acepta por uniformidad con el resto de las métricas, pero se ignora.

Consulta

start_datestring

Inicio del rango, YYYY-MM-DD. Va junto con end_date: mandar uno solo devuelve 422. Sin ninguno de los dos, la métrica cubre los últimos 7 días.

end_datestring

Fin del rango, YYYY-MM-DD, inclusive. Va junto con start_date.

Devuelve

total_messagesinteger

Turnos del rango.

total_input_tokensinteger

Entrada.

total_output_tokensinteger

Salida.

total_tokensinteger

Total.

cache_read_tokensinteger

Leídos de caché.

cache_creation_tokensinteger

Escritos a caché.

curl -sS -X GET 'https://api.niucore.com/api/v1/analytics/token-usage/by-day?start_date=2026-08-01&end_date=2026-08-31' \
  -H "Authorization: Bearer $NIUCORE_ACCESS_TOKEN"
Respuesta
{
  "status": "success",
  "message": "Operación exitosa",
  "message_code": "api_v1_ok",
  "data": {
    "total_messages": 4812,
    "total_input_tokens": 9120440,
    "total_output_tokens": 812006,
    "total_tokens": 9932446,
    "cache_read_tokens": 1904882,
    "cache_creation_tokens": 88410
  },
  "meta": {
    "request_id": "9f1c0a3e-7b2d-4f18-9a55-2c6e0d1b4a77"
  }
}