Skip to main content

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

  • date
    • date={YYYY-MM-DD}
    • Return usage for the specified date.
    • Optional
  • from/to
    • from={YYYY-MM-DD}&to={YYYY-MM-DD}
    • Return usage for the specified time range (in days).
    • Optional
  • format
    • format={format}
    • Specify the response format. Supported values are xml and json. 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

  • month
    • month={YYYY-MM}
    • Return usage for the specified month.
    • Optional
  • from/to
    • from={YYYY-MM}&to{YYYY-MM}
    • Return usage for the specified time range (in months).
    • Optional
  • format
    • format={format}
    • Specify the response format. Supported values are xml and json. 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

  • format
    • format={format}
    • Specify the response format. Supported values are xml and json. 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
  • format
    • format={format}
    • Specify the response format. Supported values are xml and json. 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
  • format
    • format={format}
    • Specify the response format. Supported values are xml and json. 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
  • format
    • format={format}
    • Specify the response format. Supported values are xml and json. 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