Skip to content
NebulaCtrlInstall

Reference

View as Markdown

Analytics API

3 operations. Every call needs a session cookie or an Authorization: Bearer nct_… token unless marked Public. Conventions, errors and scopes

GET/analytics/traffic

Traffic analytics across servers

Workspace-wide report, optionally filtered by server, service or environment. Without a service or environment filter it needs servers:read; with one it needs projects:read. Project-restricted tokens only see their own services. Window to report. Minute data covers 24 hours; longer ranges read hourly (default 7 days kept) or daily (90 days) rows.

ParameterInTypeDescription
rangequeryenum: 5m | 10m | 15m | 30m | 1h | 6h | 12h | 24h | 7d | 30d | 90dWindow to report
comparequeryenum: | prevprev adds the previous equal window as comparison
hostquerystringRestrict to one hostname
pagesquerybooleantrue (default) ranks top paths by page views (documents); false ranks every request
serverIdquerystring (uuid)Restrict to one server
serviceIdquerystring (uuid)Restrict to one service (needs projects:read)
environmentIdquerystring (uuid)Restrict to the services of one environment (needs projects:read)
Response 200 · OK · application/json
Report
  • activeHoursinteger (int64)[] | null[] | null
  • Summary
  • DeploymentMarker[] | nullrequired
  • Geo
  • geoReasonenum: geo_disabled | traffic_disabled
    Why geo is absent
  • TopItem[] | nullrequired
    Most requested paths answered 404
  • RangeInforequired
  • SeriesPoint[] | nullrequired
  • Sparklinesrequired
  • StatusCount[] | nullrequired
  • Summaryrequired
  • TopItem[] | nullrequired
  • TopItem[] | nullrequired
  • TopItem[] | nullrequired
  • TopItem[] | nullrequired
  • TopItem[] | nullrequired
  • topPathsKindenum: pages | requestsrequired
  • TopItem[] | nullrequired
  • Unrouted
Errors
  • 401Unauthorized
  • 403Forbidden
  • 404Not Found
  • 422Unprocessable Entity
  • 500Internal Server Error

Errors are RFC 9457 application/problem+json with a stable code field.

GET/servers/{serverId}/analytics

Traffic analytics of every host on a server

Same payload as the service report plus unrouted (requests that matched no service). Window to report. Minute data covers 24 hours; longer ranges read hourly (default 7 days kept) or daily (90 days) rows.

ParameterInTypeDescription
serverIdrequiredpathstring
rangequeryenum: 5m | 10m | 15m | 30m | 1h | 6h | 12h | 24h | 7d | 30d | 90dWindow to report
comparequeryenum: | prevprev adds the previous equal window as comparison
hostquerystringRestrict to one hostname
pagesquerybooleantrue (default) ranks top paths by page views (documents); false ranks every request
Response 200 · OK · application/json
Report
  • activeHoursinteger (int64)[] | null[] | null
  • Summary
  • DeploymentMarker[] | nullrequired
  • Geo
  • geoReasonenum: geo_disabled | traffic_disabled
    Why geo is absent
  • TopItem[] | nullrequired
    Most requested paths answered 404
  • RangeInforequired
  • SeriesPoint[] | nullrequired
  • Sparklinesrequired
  • StatusCount[] | nullrequired
  • Summaryrequired
  • TopItem[] | nullrequired
  • TopItem[] | nullrequired
  • TopItem[] | nullrequired
  • TopItem[] | nullrequired
  • TopItem[] | nullrequired
  • topPathsKindenum: pages | requestsrequired
  • TopItem[] | nullrequired
  • Unrouted
Errors
  • 401Unauthorized
  • 403Forbidden
  • 404Not Found
  • 422Unprocessable Entity
  • 500Internal Server Error

Errors are RFC 9457 application/problem+json with a stable code field.

GET/services/{serviceId}/analytics

Traffic analytics of a service

Aggregated from Traefik access logs on the service's server: requests, bandwidth, unique visitors (per UTC day, bots excluded), latency percentiles from merged histograms, status codes and top lists. Raw access logs, IPs and user agents are never stored. Window to report. Minute data covers 24 hours; longer ranges read hourly (default 7 days kept) or daily (90 days) rows.

ParameterInTypeDescription
serviceIdrequiredpathstring
rangequeryenum: 5m | 10m | 15m | 30m | 1h | 6h | 12h | 24h | 7d | 30d | 90dWindow to report
comparequeryenum: | prevprev adds the previous equal window as comparison
hostquerystringRestrict to one hostname of the service
pagesquerybooleantrue (default) ranks top paths by page views (documents); false ranks every request
Response 200 · OK · application/json
Report
  • activeHoursinteger (int64)[] | null[] | null
  • Summary
  • DeploymentMarker[] | nullrequired
  • Geo
  • geoReasonenum: geo_disabled | traffic_disabled
    Why geo is absent
  • TopItem[] | nullrequired
    Most requested paths answered 404
  • RangeInforequired
  • SeriesPoint[] | nullrequired
  • Sparklinesrequired
  • StatusCount[] | nullrequired
  • Summaryrequired
  • TopItem[] | nullrequired
  • TopItem[] | nullrequired
  • TopItem[] | nullrequired
  • TopItem[] | nullrequired
  • TopItem[] | nullrequired
  • topPathsKindenum: pages | requestsrequired
  • TopItem[] | nullrequired
  • Unrouted
Errors
  • 401Unauthorized
  • 403Forbidden
  • 404Not Found
  • 422Unprocessable Entity
  • 500Internal Server Error

Errors are RFC 9457 application/problem+json with a stable code field.