> For AI agents: [llms.txt](https://docs.trustedauth.com/llms.txt) provides a Markdown index of this documentation. # Lists a page of entitlement usage information `POST /api/web/v4/tenants/entitlements/usage` Returns tenant usage information for the provided search parameters. Caller requires the TENANTS:VIEW permission. The following searchByAttributes are supported: The orderByAttribute supports these attribute names: startTime. ## Request Body Required. ### application/json Schema ```json { "type": "object", "properties": { "attributes": { "type": "array", "description": "Users search only: additional, non-core attributes to include in the returned object. Attribute names are specific to the returned object.", "items": { "type": "string", "description": "Users search only: additional, non-core attributes to include in the returned object. Attribute names are specific to the returned object." } }, "cursor": { "type": "string", "description": "Identifies the page to return when paging over a result set--if present, search by / order by attributes are ignored." }, "limit": { "maximum": 100, "minimum": 1, "type": "integer", "description": "Identifies the maximum number of items to include in a page (1-100).", "format": "int32" }, "orderByAttribute": { "required": [ "ascending", "name" ], "type": "object", "properties": { "ascending": { "type": "boolean", "description": "Identifies whether to order results in ascending order." }, "name": { "type": "string", "description": "Identifies the attribute." } }, "description": "An attribute used to sort the result from a search.", "title": "OrderByAttribute" }, "searchByAttributes": { "type": "array", "description": "Identifies attributes for searching purposes. Some end-points have pre-defined values and ignore this attribute.", "items": { "required": [ "name", "operator" ], "type": "object", "properties": { "name": { "type": "string", "description": "Identifies the attribute we are searching for." }, "operator": { "type": "string", "description": "Identifies the operator.", "enum": [ "EQUALS", "NOT_EQUALS", "CONTAINS", "NOT_CONTAINS", "STARTS_WITH", "ENDS_WITH", "GREATER_THAN", "GREATER_THAN_OR_EQUAL", "LESS_THAN", "LESS_THAN_OR_EQUAL", "IN", "EXISTS", "NOT_EXISTS" ] }, "value": { "type": "string", "description": "Identifies the value of the attribute we are searching for." } }, "description": "An attribute used during paging and/or searching.", "title": "SearchByAttribute" } } }, "description": "Parameters specifying search attributes or a cursor to get results from a previous search.", "title": "SearchParms" } ``` ## Responses ### 200 Successful #### application/json Schema ```json { "required": [ "results" ], "type": "object", "properties": { "paging": { "required": [ "limit" ], "type": "object", "properties": { "limit": { "maximum": 100, "minimum": 1, "type": "integer", "description": "The page limit used (1-100)", "format": "int32" }, "nextCursor": { "type": "string", "description": "The cursor pointing to the next page." }, "prevCursor": { "type": "string", "description": "The cursor pointing to the previous page." } }, "description": "Contains navigation information.", "title": "Paging" }, "results": { "type": "array", "description": "A single page with the list of usage info found.", "items": { "required": [ "aggregationPeriod", "count", "endTime", "id", "startTime", "tenantId", "trial", "usageType" ], "type": "object", "properties": { "aggregationPeriod": { "type": "string", "description": "The aggregation period used.", "example": "DAILY", "enum": [ "DAILY", "WEEKLY", "MONTHLY" ] }, "bundleType": { "type": "string", "description": "The service bundle." }, "count": { "type": "integer", "description": "The entitlements used in the aggregation period.", "format": "int64" }, "endTime": { "type": "string", "description": "The end time of the aggregation period.", "example": "2019-02-19T00:00:00Z" }, "id": { "type": "string", "description": "The unique UUID for this usage info." }, "startTime": { "type": "string", "description": "The start time of the aggregation period.", "example": "2019-02-19T00:00:00Z" }, "tenantId": { "type": "string", "description": "The unique UUID of the tenant." }, "trial": { "type": "boolean", "description": "Whether the usage is associated to a trial tenant.", "example": true }, "usageType": { "type": "string", "description": "The type of this entitlement.", "example": "USERS", "enum": [ "USERS", "ISSUANCE" ] } }, "description": "Entitlement usage information of a tenant.", "title": "UsageInfo" } } }, "description": "Contains paging information and the results from a tenant usage info search.", "title": "UsageInfoPage" } ``` ### 400 Bad Request #### application/json Schema ```json { "type": "object", "properties": { "errorCode": { "type": "string", "description": "Error Codes specific to cause of failure.", "example": "invalid_user_response" }, "errorMessage": { "type": "string", "description": "Additional Error Message describing the error.", "example": "Application id cannot be null" }, "parameters": { "type": "array", "description": "Optional additional error information.", "items": { "type": "object", "description": "Optional additional error information." } } }, "description": "Object containing information about errors reported by services.", "title": "ErrorInfo" } ``` ### 401 Access denied #### application/json Schema ```json { "type": "object", "properties": { "errorCode": { "type": "string", "description": "Error Codes specific to cause of failure.", "example": "invalid_user_response" }, "errorMessage": { "type": "string", "description": "Additional Error Message describing the error.", "example": "Application id cannot be null" }, "parameters": { "type": "array", "description": "Optional additional error information.", "items": { "type": "object", "description": "Optional additional error information." } } }, "description": "Object containing information about errors reported by services.", "title": "ErrorInfo" } ``` ### 403 Forbidden #### application/json Schema ```json { "type": "object", "properties": { "errorCode": { "type": "string", "description": "Error Codes specific to cause of failure.", "example": "invalid_user_response" }, "errorMessage": { "type": "string", "description": "Additional Error Message describing the error.", "example": "Application id cannot be null" }, "parameters": { "type": "array", "description": "Optional additional error information.", "items": { "type": "object", "description": "Optional additional error information." } } }, "description": "Object containing information about errors reported by services.", "title": "ErrorInfo" } ``` ### 404 Not Found #### application/json Schema ```json { "type": "object", "properties": { "errorCode": { "type": "string", "description": "Error Codes specific to cause of failure.", "example": "invalid_user_response" }, "errorMessage": { "type": "string", "description": "Additional Error Message describing the error.", "example": "Application id cannot be null" }, "parameters": { "type": "array", "description": "Optional additional error information.", "items": { "type": "object", "description": "Optional additional error information." } } }, "description": "Object containing information about errors reported by services.", "title": "ErrorInfo" } ``` ### 409 Conflict #### application/json Schema ```json { "type": "object", "properties": { "errorCode": { "type": "string", "description": "Error Codes specific to cause of failure.", "example": "invalid_user_response" }, "errorMessage": { "type": "string", "description": "Additional Error Message describing the error.", "example": "Application id cannot be null" }, "parameters": { "type": "array", "description": "Optional additional error information.", "items": { "type": "object", "description": "Optional additional error information." } } }, "description": "Object containing information about errors reported by services.", "title": "ErrorInfo" } ``` ## Security Requirements ```json [ { "AdminAPIAuthentication": [ "TENANTS:VIEW" ] } ] ```