Licensing Operations Export Usage

Licensing Operations Export Usage
CSV or JSON export of per-host usage

Returns a CSV export of per-host core usage as the text/csv response body (the code sets no explicit charset), sent as an attachment named hyperarmor-core-usage.csv. The file starts with seven comment lines that begin with a hash sign and give the evaluation time (ISO-8601 with offset), license state, entitled, consumed and available cores and the inactivity threshold in days. The column header row follows, in this order, hostname, vcenter, cpu_packages, physical_cores, minimum_applied, charged_cores, licensing_status, last_check_in_utc, topology_known, and then one row for every host. The hostname and vcenter values are always enclosed in double quotes with embedded quotes doubled, and a value that starts with =, +, -, @, tab, CR or LF is prefixed with a single quote to neutralise spreadsheet formulas. The cpu_packages, physical_cores and last_check_in_utc cells are empty when the value is unknown. The same data is returned as a JSON object (evaluatedAt, licenseState, entitledCores, consumedCores, availableCores, inactivityThresholdDays and a hosts array of HostCoreUsageDto) when the request sends an Accept header that prefers application/json; the CSV is returned for text/csv, / or no Accept header, and any other Accept value gets a 406 NOT_ACCEPTABLE. The export takes no parameters, and the controller applies no filter, paging or row limit. Requires the ADMIN, SECURITY_OPERATOR or AUDITOR role.

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

200 OK successful response envelope. The export of per-host core usage, as a CSV attachment or as JSON depending on the Accept header

Returns LicenseUsageExportDto of type(s) application/json
{
    "evaluatedAt": "2026-01-15T09:30:00Z",
    "licenseState": "ACTIVE",
    "entitledCores": 64,
    "consumedCores": 48,
    "availableCores": 16,
    "inactivityThresholdDays": 14,
    "hosts": [
        {
            "agentId": "1",
            "hostname": "esx02.example.com",
            "vcenter": "db-1",
            "cpuPackages": 2,
            "physicalCores": 32,
            "topologyKnown": true,
            "minimumApplied": false,
            "chargedCores": 32,
            "lastCheckInAt": "2026-01-15T09:29:30Z",
            "licensingStatus": "CONSUMING"
        }
    ]
}
string As date-time As date-time
evaluatedAt
Required  

Time the license pool was evaluated

string
licenseState
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
integer As int64 As int64
entitledCores
Required  

Cores entitled by the installed licenses

integer As int64 As int64
consumedCores
Required  

Cores charged across all hosts

integer As int64 As int64
availableCores
Required  

Entitled cores not yet consumed

integer As int32 As int32
inactivityThresholdDays
Required  

Days without a check-in after which a host is RECLAIMED

array of object
hosts
Required  

One entry per host, unfiltered and unpaged


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); LICENSE_REQUIRED or LICENSE_EXPIRED while the license pool is restricted (no license, or expired past grace) (exempt: every route under /api/v1/auth, GET /api/v1/user/preferences, GET /api/v1/licensing/summary and POST /api/v1/licensing/licenses)

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.


406

406 Not Acceptable: NOT_ACCEPTABLE when the Accept header allows neither text/csv nor application/json

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/usage/export