Niucore

API reference

Analytics

Usage, activity and token consumption metrics.

Activity summary

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

Scope: analytics:read

Interactions, users and average per day within the range. Without a range, the last seven days.

Not paginated

It returns the complete series for the requested range. meta carries only request_id — no page, size or total — and pagination parameters are ignored. What bounds the result is start_date/end_date, which default to the last 7 days.

Credentials limited to libraries

If the credential is restricted to specific libraries, library_id is required and must be in its list. Without it the answer would be the company total, which includes what the credential cannot see: the API asks for it instead of silently narrowing.

Query

start_datestring

Range start, YYYY-MM-DD. Goes together with end_date: sending only one returns 422. With neither, the metric covers the last 7 days.

end_datestring

Range end, YYYY-MM-DD, inclusive. Goes together with start_date.

library_idinteger

Narrows the metric to one library. Required if the credential is limited to specific libraries.

Returns

daystring

Date, YYYY-MM-DD.

total_interactionsinteger

Turns that day.

total_usersinteger

Users who conversed.

averagenumber

Interactions per user.

Errors

  • 403api_v1_resource_not_allowedlibrary_id is missing on a narrowed credential, or the one sent is outside its list. data.required_query_param says so.
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"
Response
{
  "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"
  }
}

User activity

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

Scope: analytics:read

For each day in the range: how many users existed, how many conversed and how many did not.

Not paginated

It returns the complete series for the requested range. meta carries only request_id — no page, size or total — and pagination parameters are ignored. What bounds the result is start_date/end_date, which default to the last 7 days.

Credentials limited to libraries

If the credential is restricted to specific libraries, library_id is required and must be in its list. Without it the answer would be the company total, which includes what the credential cannot see: the API asks for it instead of silently narrowing.

Query

start_datestring

Range start, YYYY-MM-DD. Goes together with end_date: sending only one returns 422. With neither, the metric covers the last 7 days.

end_datestring

Range end, YYYY-MM-DD, inclusive. Goes together with start_date.

library_idinteger

Narrows the metric to one library. Required if the credential is limited to specific libraries.

Returns

daystring

Date, YYYY-MM-DD.

total_usersinteger

Users accumulated up to that day.

active_usersinteger

Conversed.

inactive_usersinteger

Did not converse.

total_interactionsinteger

Turns that day.

averagenumber

Turns per active user.

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"
Response
{
  "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"
  }
}

Interactions per weekday

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

Scope: analytics:read

Turns per day of the range, with the weekday name.

Not paginated

It returns the complete series for the requested range. meta carries only request_id — no page, size or total — and pagination parameters are ignored. What bounds the result is start_date/end_date, which default to the last 7 days.

Credentials limited to libraries

If the credential is restricted to specific libraries, library_id is required and must be in its list. Without it the answer would be the company total, which includes what the credential cannot see: the API asks for it instead of silently narrowing.

Query

start_datestring

Range start, YYYY-MM-DD. Goes together with end_date: sending only one returns 422. With neither, the metric covers the last 7 days.

end_datestring

Range end, YYYY-MM-DD, inclusive. Goes together with start_date.

library_idinteger

Narrows the metric to one library. Required if the credential is limited to specific libraries.

Returns

daystring

Weekday name.

datestring

Date, YYYY-MM-DD.

totalinteger

Turns that day.

total_usersinteger

Distinct users who interacted that day.

curl -sS -X GET 'https://api.niucore.com/api/v1/analytics/interactions-by-weekday' \
  -H "Authorization: Bearer $NIUCORE_ACCESS_TOKEN"
Response
{
  "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"
  }
}

Top questions

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

Scope: analytics:read

The most queried topics of the period, grouped by topic.

Not paginated

It returns the complete series for the requested range. meta carries only request_id — no page, size or total — and pagination parameters are ignored. What bounds the result is start_date/end_date, which default to the last 7 days.

Credentials limited to libraries

If the credential is restricted to specific libraries, library_id is required and must be in its list. Without it the answer would be the company total, which includes what the credential cannot see: the API asks for it instead of silently narrowing.

Query

start_datestring

Range start, YYYY-MM-DD. Goes together with end_date: sending only one returns 422. With neither, the metric covers the last 7 days.

end_datestring

Range end, YYYY-MM-DD, inclusive. Goes together with start_date.

library_idinteger

Narrows the metric to one library. Required if the credential is limited to specific libraries.

Returns

topicstring

The topic.

labelsstring[]

The range's dates, YYYY-MM-DD, one per day.

datanumber[]

Queries on that topic per day, aligned with 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"
Response
{
  "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"
  }
}

Interactions per library

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

Scope: analytics:read

How much each library was queried.

Not paginated

It returns the complete series for the requested range. meta carries only request_id — no page, size or total — and pagination parameters are ignored. What bounds the result is start_date/end_date, which default to the last 7 days.

Credentials limited to libraries

If the credential is restricted to specific libraries, library_id is required and must be in its list. Without it the answer would be the company total, which includes what the credential cannot see: the API asks for it instead of silently narrowing.

Query

start_datestring

Range start, YYYY-MM-DD. Goes together with end_date: sending only one returns 422. With neither, the metric covers the last 7 days.

end_datestring

Range end, YYYY-MM-DD, inclusive. Goes together with start_date.

library_idinteger

Narrows the metric to one library. Required if the credential is limited to specific libraries.

Returns

workspacestring

Library name.

totalinteger

Interactions.

curl -sS -X GET 'https://api.niucore.com/api/v1/analytics/interactions-by-library' \
  -H "Authorization: Bearer $NIUCORE_ACCESS_TOKEN"
Response
{
  "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"
  }
}

Files per library

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

Scope: analytics:read

File count per library. It is the only metrics endpoint that does not require library_id on narrowed credentials: only the allowed ones are listed.

Not paginated

It returns the complete series for the requested range. meta carries only request_id — no page, size or total — and pagination parameters are ignored. What bounds the result is start_date/end_date, which default to the last 7 days.

Returns

library_idinteger

Identifier.

namestring

Name.

filesinteger

Live files.

curl -sS -X GET 'https://api.niucore.com/api/v1/analytics/files-by-library' \
  -H "Authorization: Bearer $NIUCORE_ACCESS_TOKEN"
Response
{
  "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"
  }
}

Usage per model

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

Scope: analytics:read

Tokens consumed, broken down by model and provider.

Not paginated

It returns the complete series for the requested range. meta carries only request_id — no page, size or total — and pagination parameters are ignored. What bounds the result is start_date/end_date, which default to the last 7 days.

What the total covers

It returns company-wide usage only if the credential is not limited to specific libraries and the user holds metrics.read.all. In every other case the total is that of the user the credential acts for — never more than that person can already see.

Heads up

These two endpoints only look at start_date and end_date. library_id is accepted for uniformity with the other metrics, but it is ignored.

Query

start_datestring

Range start, YYYY-MM-DD. Goes together with end_date: sending only one returns 422. With neither, the metric covers the last 7 days.

end_datestring

Range end, YYYY-MM-DD, inclusive. Goes together with start_date.

Returns

model_namestring

Model.

provider_namestring

Provider.

is_autoboolean

Turns resolved by the balancer. With true, auto_breakdown carries which model answered each.

message_countinteger

Turns.

input_tokensinteger

Input tokens.

output_tokensinteger

Output tokens.

total_tokensinteger

Total.

cache_read_tokensinteger

Tokens read from cache. They are not included in input_tokens.

cache_creation_tokensinteger

Tokens written to cache.

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"
Response
{
  "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"
  }
}

Aggregate usage

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

Scope: analytics:read

The range totals, as a single object — not a per-day series.

Not paginated

It returns the complete series for the requested range. meta carries only request_id — no page, size or total — and pagination parameters are ignored. What bounds the result is start_date/end_date, which default to the last 7 days.

What the total covers

It returns company-wide usage only if the credential is not limited to specific libraries and the user holds metrics.read.all. In every other case the total is that of the user the credential acts for — never more than that person can already see.

Heads up

These two endpoints only look at start_date and end_date. library_id is accepted for uniformity with the other metrics, but it is ignored.

Query

start_datestring

Range start, YYYY-MM-DD. Goes together with end_date: sending only one returns 422. With neither, the metric covers the last 7 days.

end_datestring

Range end, YYYY-MM-DD, inclusive. Goes together with start_date.

Returns

total_messagesinteger

Turns in the range.

total_input_tokensinteger

Input.

total_output_tokensinteger

Output.

total_tokensinteger

Total.

cache_read_tokensinteger

Read from cache.

cache_creation_tokensinteger

Written to cache.

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"
Response
{
  "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"
  }
}