Customer usage (TCA-9999)
The Customer Usage service allows the tracking of various usage and limit metrics of Spectra Intelligence services provisioned to the authenticated account, or to all accounts in a company.
Daily, monthly and date range queries return the number of queries (and bytes if file size based limiting applies to the product) made in the requested time range for the current user, or the combined usage for all accounts within the company the current user belongs to.
The Active YARA rulesets query returns information about the number of active YARA rulesets for the Spectra Intelligence account that sent the request.
Quota limits queries return current service quota limits for APIs accessible to the authenticated user, or to all accounts within the company the current user belongs to.
Provisioned services with no registered usage in the requested time range are not included in the response.
This API is not rate limited.
Daily Usage
Current User
This query returns information about daily service usage for the Spectra Intelligence account that sent the request. If the date is not specified in the request, the service returns usage for the current date. The users can also specify a from-to time range (in days), to a maximum interval of 365 days.
GET /api/customer_usage/v1/usage/daily
Company
This query returns information about combined daily service usage for all users in the company. If the date is not specified, the service returns usage for the current day. The users can also specify a from-to time range (in days), up to a maximum interval of 365 days.
GET /api/customer_usage/v1/usage/company/daily
Request Parameters
datedate={YYYY-MM-DD}- Return usage for the specified date.
- Optional
from/tofrom={YYYY-MM-DD}&to={YYYY-MM-DD}- Return usage for the specified time range (in days).
- Optional
formatformat={format}- Specify the response format. Supported values are
xmlandjson. The default is XML. - Optional
Response Format
The allocation field containing the list of entries with name, number_of_queries, and used_bytes values will be returned only in case there is usage.
For a Single Day
XML
JSON
{
"rl": {
"date": "2020-02-01",
"usage_report": [
{
"product": "TCA-0101 File Reputation",
"number_of_queries": 13487257
},
{
"product": "TCAI-0011 Sample Submission Counter",
"number_of_queries": 59,
"used_bytes": 311816
}
]
}
}
When Using From/To
XML
JSON
{
"rl": {
"usage_reports": [
{
"date": "2020-01-31",
"usage_report": [
{
"product": "TCA-0101 File Reputation",
"number_of_queries": 53967760
}
]
},
{
"date": "2020-02-01",
"usage_report": [
{
"product": "TCA-0101 File Reputation",
"number_of_queries": 13487257
}
]
}
]
}
}
Monthly Usage
Current User
This query returns information about monthly service usage for the Spectra Intelligence account that sent the request. If the month is not specified, the service returns usage for the current month. The users can also specify a from-to time range (in months).
GET /api/customer_usage/v1/usage/monthly
Company
This query returns information about combined monthly service usage for all users in the company. If the month is not specified, the service returns usage for the current month. The users can also specify a from-to time range (in months).
GET /api/customer_usage/v1/usage/company/monthly
Request Parameters
monthmonth={YYYY-MM}- Return usage for the specified month.
- Optional
from/tofrom={YYYY-MM}&to{YYYY-MM}- Return usage for the specified time range (in months).
- Optional
formatformat={format}- Specify the response format. Supported values are
xmlandjson. The default is XML. - Optional
Response Format
This query returns information about monthly service usage for the Spectra Intelligence account that sent the request. The allocation field containing the list of entries with name, number_of_queries, and used_bytes values will be returned only in case there is usage.
For a Single Month
XML
JSON
{
"rl": {
"month": "2023-10",
"usage_report": [
...
{
"product": "TCAI-0011 Sample Submission Counter",
"number_of_queries": 10,
"used_bytes": 530000,
"allocation": [
{
"name": "Portal",
"number_of_queries": 3,
"used_bytes": 320000
},
{
"name": "CLI-01",
"number_of_queries": 7,
"used_bytes": 210000
}
]
}
...
]
}
}
When Using From/To
XML
JSON
{
"rl": {
"usage_reports": [
{
"month": "2020-01",
"usage_report": [
{
"product": "TCA-0101 File Reputation",
"number_of_queries": 1384316486
}
]
},
{
"month": "2020-02",
"usage_report": [
{
"product": "TCA-0101 File Reputation",
"number_of_queries": 1332893230
}
]
}
]
}
}
Date Range Usage
Current User
This query returns total usage for all product licenses with a fixed quota over a single date range. Use this endpoint for products with quotas that don't reset on a daily or monthly basis. The endpoint accepts no additional date specifying parameters, instead always returning total usage for the account in question.
Some services may count the quota in used bytes instead of requests. In this case used_bytes value is included as a response field on a per-product basis.
GET /api/customer_usage/v1/usage/date_range
Company
This query returns information about combined date range service usage for all users in the company. The endpoint accepts no additional date-specifying parameters, instead always returning total usage for the account in question.
Some services may count the quota in used bytes instead of requests. In this case used_bytes value is included as a response field on a per-product basis.
GET /api/customer_usage/v1/usage/company/date_range
Request Parameters
formatformat={format}- Specify the response format. Supported values are
xmlandjson. The default is XML. - Optional
Response Format
The allocation field containing the list of entries with name, number_of_queries, and used_bytes values will be returned only in case there is usage.
XML
JSON
{
"rl": {
"usage_reports": [
{
"start_date": "2022-04-01",
"end_date": "2023-03-31",
"products": [
"TCAI-0011 Sample Submission Counter"
],
"count": 566,
"used_bytes": 4123890
}
]
}
}
IV. Active YARA rulesets
This query returns information about the number of active YARA rulesets for the Spectra Intelligence account that sent the request. Historical data is not shown.
GET /api/customer_usage/v1/usage/yara
formatformat={format}- Specify the response format. Supported values are
xmlandjson. The default is XML. - Optional
Response Format
XML
JSON
{
"rl": {
"product": "TCA-0303 Yara Hunting",
"number_of_active_rulesets": 23
}
}
V. Quota Limits
Current User
This query returns current quota limits for APIs accessible to the authenticated user. Products are grouped into one object if they share the usage quota and access rights. This means that the same users and products can appear multiple times in the response.
If product quota is limited by the number of bytes, limit field may be omitted, limit_size field is returned instead. If a product license has a fixed expiry date, start_date and end_date are included with the limit. If the product enforces a limit on the number of bytes for each submitted file, it is included as limit_size_per_file within the appropriate limit.
A product license may include an additional free usage quota which resets alongside the standard quota (e.g. free quota for monthly licenses also resets monthly). This quota has a separate expiry period. The information about the quota is available via the free_flex field.
Products related to Spectra Assure may also include an entitlements object associated with each limit, containing max_package_size - the largest processable package size in bytes, as well as various feature flags included with the product license.
GET /api/customer_usage/v1/limits
formatformat={format}- Specify the response format. Supported values are
xmlandjson. The default is XML. - Optional
Company
This query returns current quota limits for APIs available to all users belonging to the authenticated user's company. Products are grouped into one object if they share the usage quota and access rights. This means that the same users and products can appear multiple times in the response.
GET /api/customer_usage/v1/limits/company
formatformat={format}- Specify the response format. Supported values are
xmlandjson. The default is XML. - Optional
Response Format
The response format is identical for both endpoints, differing only in the number of listed services. In the following examples, user1 will receive the same response for both the Current User and Company endpoints, while user2 will not receive the TCA-0301 object when querying the Current User endpoint, as it is only accessible to user1.
XML
JSON
{
"rl": {
"limits": [
{
"limit": 500000,
"limit_type": "daily",
"limit_exceeded" : true,
"products": ["TCA-0101 File Reputation", "TCA-0104 RLDATA", "TCA-0103 Historic Multi-AV Scan Records"],
"users": ["user1","user2","user3"]
},
{
"limit": 1000,
"limit_type": "monthly",
"limit_exceeded" : false,
"products": ["TCA-0301 RHA Functional Similarity"],
"users": ["user1"],
"start_date": "2022-09-15",
"end_date": "2023-09-15"
},
{
"limit_size": {
"value": 1000,
"unit": "GB"
},
"limit_type": "monthly",
"limit_exceeded" : false,
"products": ["TCAI-0011 Sample Submission Counter"],
"users": ["user1"],
"start_date": "2022-09-15",
"end_date": "2023-09-15",
"free_flex": {
"limit_size": {
"value": 1000,
"unit": "GB"
},
"start_date": "2022-09-15",
"end_date": "2022-12-15"
},
"limit_size_per_file": {
"value": 1,
"unit": "GB"
},
"entitlements": {
"hardening": true,
"licenses": true,
"malware": true,
"max_package_size": 10737418240,
"secrets": true,
"tampering": true,
"vulnerabilities": true
}
}
]
}
}
Response format for API usage (XML)
Response format for secure.software quotas (JSON)
The allocation field containing the list of entries with name and size values will be returned only in case there exists a total allocation limit.
{
"rl": {
"limits": [
...
{
"limit_size": {
"value": 5,
"unit": "GB"
},
"limit_type": "monthly",
"limit_exceeded" : false,
"products": ["TCAI-0011 Sample Submission Counter"],
"users": ["user1"],
"start_date": "2023-09-15",
"end_date": "2024-09-15",
"allocation": [
{
"name": "Portal",
"size": {
"value": 3000000000,
"unit": "byte"
}
},
{
"name": "CLI-01",
"size": {
"value": 2000000000,
"unit": "byte"
}
}
]
}
...
]
}
}
Examples
Monthly usage for the current user from January to March 2020, in JSON format
/api/customer_usage/v1/usage/monthly?from=2020-01&to=2020-03&format=json
Daily usage for the entire company from January 13th to February 14th
/api/customer_usage/v1/usage/company/daily?from=2020-01-13&to=2020-02-14
Quota limits for the current user
/api/customer_usage/v1/limits