Licensing Operations Get Summary

Licensing Operations Get Summary
Pooled entitlement, consumption and state

Returns pooled entitlement, measured consumption and licensing lifecycle state. Requires the ADMIN, SECURITY_OPERATOR or AUDITOR role.

Request
URI
GET
https://{api_host}/api/v1/licensing/summary
COPY
Authentication
This operation uses the following authentication methods.
Responses
200

200 OK successful response envelope. The pooled entitlement, the measured consumption and the licensing state

Returns LicenseSummaryDto of type(s) application/json
{
    "state": "ACTIVE",
    "restricted": false,
    "overCapacity": false,
    "validLicenseCount": 1,
    "entitledCores": 64,
    "consumedCores": 48,
    "availableCores": 16,
    "overageCores": 0,
    "registeredAgents": 2,
    "onlineAgents": 1,
    "offlineAgents": 1,
    "consumingHosts": 2,
    "reclaimedHosts": 0,
    "hostsWithUnknownTopology": 0,
    "inactiveAgentDays": 14,
    "nextExpiry": {
        "serialNumber": "0000740016",
        "validTo": "2026-02-28",
        "daysLeft": 44
    },
    "lastExpiry": {
        "serialNumber": "0000740016",
        "validTo": "2026-02-28",
        "daysLeft": 44
    },
    "graceEndsAt": "2026-03-08T00:00:00Z",
    "evaluatedAt": "2026-01-15T09:30:00Z",
    "inventoryObservedAt": "2026-01-15T09:29:30Z"
}
string
state
Required  

Overall console licensing lifecycle state

  • NO_LICENSE: No license is ACTIVE and none has ever been valid
  • NOT_YET_VALID: No longer produced: validFrom is informational, so a license counts from the day it is installed. Kept so clients and the telemetry report still recognise the value
  • ACTIVE: At least one license is ACTIVE and the farthest-expiring one has more than 30 days left
  • EXPIRING: At least one license is ACTIVE but the farthest-expiring one has 30 days or fewer left
  • GRACE: No license is ACTIVE although one has been valid before, and the grace period of 7 days after its last valid day has not ended
  • RESTRICTED: No license is ACTIVE although one has been valid before, and the grace period has ended; restricted is true
Enumeration: NO_LICENSE, NOT_YET_VALID, ACTIVE, EXPIRING, GRACE, RESTRICTED
boolean
restricted
Required  

True when state is RESTRICTED, that is when no license is ACTIVE and the grace period has ended

boolean
overCapacity
Required  

True when entitledCores is above 0 and consumedCores is higher than entitledCores

integer As int32 As int32
validLicenseCount
Required  

Number of installed licenses whose status is ACTIVE

integer As int64 As int64
entitledCores
Required  

Total cores licensed: the sum of contributionCores over the ACTIVE licenses

integer As int64 As int64
consumedCores
Required  

Total cores charged across all registered hosts; a RECLAIMED host is charged 0

integer As int64 As int64
availableCores
Required  

entitledCores minus consumedCores, never below 0

integer As int64 As int64
overageCores
Required  

consumedCores minus entitledCores, never below 0

integer As int32 As int32
registeredAgents
Required  

Number of registered Agents whose lifecycle state is not DELETED

integer As int32 As int32
onlineAgents
Required  

Number of hosts whose licensingStatus is CONSUMING

integer As int32 As int32
offlineAgents
Required  

Number of hosts whose licensingStatus is OFFLINE_WITHIN_THRESHOLD or RECLAIMED

integer As int32 As int32
consumingHosts
Required  

Number of hosts whose licensingStatus is CONSUMING or OFFLINE_WITHIN_THRESHOLD, which are the hosts that are charged

integer As int32 As int32
reclaimedHosts
Required  

Number of hosts whose licensingStatus is RECLAIMED

integer As int32 As int32
hostsWithUnknownTopology
Required  

Number of hosts whose CPU topology is unknown (topologyKnown is false), including RECLAIMED hosts, which are charged 0; a host with no topology, or with only packages or only cores known, is charged the 16-core floor; an optional estimate from the known value exists but is off by default (property vtp.licensing.partial-topology-estimate.enabled)

integer As int32 As int32
inactiveAgentDays
Required  

Inactivity window in days used for this evaluation: a host without a check-in for longer is RECLAIMED (the inactiveAgentDays licensing setting)

nextExpiry
Optional

Earliest-expiring ACTIVE license

lastExpiry
Optional

Farthest-expiring ACTIVE license; drives EXPIRING and the expiry modal

string As date-time As date-time
graceEndsAt
Optional

End of the grace period, 00:00 UTC seven days after the day following the latest validTo date recorded for any started license that is not INVALID (that date never moves back); null when no such license has ever existed

string As date-time As date-time
evaluatedAt
Required  

Time of the evaluation; an evaluation is reused for 30 seconds unless a refresh is forced

string As date-time As date-time
inventoryObservedAt
Optional

Latest lastCheckInAt among the registered hosts; null when no host has one


401

401 Unauthorized: UNAUTHENTICATED when the VTP_SESSION cookie is missing, unknown, expired or revoked

Returns Unauthenticated of type(s) application/json
{
    "errorCode": "string",
    "message": "string",
    "path": "string",
    "timestamp": "string",
    "reason": "string"
}
errorCode
Required  

Stable machine-readable error code. The known values are listed in ApiErrorCode; the set is not closed, so a client must tolerate an unlisted value.

string
message
Required  

Human-readable error description

string
path
Required  

Request URI path that produced the error

string As date-time As date-time
timestamp
Required  

Timestamp when the error occurred as an ISO 8601 date-time with offset

string
reason
Optional

A finer code, present only where an endpoint documents it. The Rule Pack endpoints' PACK_ENTRY_INVALID carries the import core's code here.


403

403 Forbidden: PASSWORD_CHANGE_REQUIRED when the account must change its password first (only GET /api/v1/auth/session, POST /api/v1/auth/logout and POST /api/v1/auth/change-password are exempt)

Returns ApiErrorResponse of type(s) application/json
{
    "errorCode": "string",
    "message": "string",
    "path": "string",
    "timestamp": "string",
    "reason": "string"
}
errorCode
Required  

Stable machine-readable error code. The known values are listed in ApiErrorCode; the set is not closed, so a client must tolerate an unlisted value.

string
message
Required  

Human-readable error description

string
path
Required  

Request URI path that produced the error

string As date-time As date-time
timestamp
Required  

Timestamp when the error occurred as an ISO 8601 date-time with offset

string
reason
Optional

A finer code, present only where an endpoint documents it. The Rule Pack endpoints' PACK_ENTRY_INVALID carries the import core's code here.


500

500 Internal Server Error: INTERNAL_ERROR when the server fails unexpectedly; the message carries no detail

Returns InternalError of type(s) application/json
{
    "errorCode": "string",
    "message": "string",
    "path": "string",
    "timestamp": "string",
    "reason": "string"
}
errorCode
Required  

Stable machine-readable error code. The known values are listed in ApiErrorCode; the set is not closed, so a client must tolerate an unlisted value.

string
message
Required  

Human-readable error description

string
path
Required  

Request URI path that produced the error

string As date-time As date-time
timestamp
Required  

Timestamp when the error occurred as an ISO 8601 date-time with offset

string
reason
Optional

A finer code, present only where an endpoint documents it. The Rule Pack endpoints' PACK_ENTRY_INVALID carries the import core's code here.


Code Samples
COPY
                    curl -H 'Authorization: <value>' https://{api_host}/api/v1/licensing/summary