Skip to main content

Customer usage (TCA-9999)

The TCA-9999 API provides authenticated Spectra Intelligence customers with full visibility and control over their licensed services.
It enables:

  • Viewing company information and users
  • Creating and managing users
  • Listing and managing licenses and limits
  • Monitoring usage and limits
  • Configuring automated usage alerts

All responses are returned in JSON.
Authentication uses Basic Auth with Spectra Intelligence credentials.

Licensing and Management endpoints are rate limited to 12 requests per minute.

Usage and Monitoring endpoints are not rate limited.

Licensing and Management​

Company​

Company Information​

Returns the number of users and the company name for the company the authenticated user belongs to.

GET /api/customer_usage/v1/management/companies

Response

{
  "name": "Company",
  "user_count": 250
}

Response Fields

  • name
    • The name of the company.
    • Type: string
    • Always present.
  • user_count
    • The number of users in the company.
    • Type: integer
    • Always present.

Users​

Create User​

Creates a new user.

important

This is the only user-related endpoint that returns a password for the created user. If the password is lost, create a new password using the reset-password endpoint.

important

Once created, users cannot be deleted. To disable a user, set the enabled field to false. There is a global limit of 1000 users, after which no new users can be created.

POST /api/customer_usage/v1/management/users

Request Fields

  • username
    • The username of the user to create. Must be alphanumeric, and / is allowed.
    • The first and last characters must be alphanumeric. This is the last segment of the username, without the /u/company/ prefix.
    • The value cannot contain test, demo, temp, or trial.
    • Required
  • email_addresses[]
    • The email addresses of the user to create.
    • Required
  • description
    • User description.
    • Required
  • enabled
    • Whether the user is enabled.
    • Required
{
  "username": "username",
  "email_addresses": ["email1@gmail.com","email2@gmail.com"],
  "description": "User description",
  "enabled": true
}

Response

{
  "rl": {
    "created_at": "2025-10-15T05:21:38+0000",
    "description": "User description",
    "email_addresses": [
      "email1@gmail.com",
      "email2@gmail.com"
    ],
    "enabled": true,
    "password": "p4ssw0rd",
    "updated_at": null,
    "username": "u/company/user"
  }
}

Response Fields

  • created_at
    • The date and time when the user was created.
    • Type: string
    • Always present.
  • description
    • The user description.
    • Type: string
    • Optional.
  • email_addresses[]
    • The list of email addresses associated with the user.
    • Type: array[string]
    • Always present.
  • enabled
    • Whether the user is currently enabled.
    • Type: boolean
    • Always present.
  • password
    • The generated password for the new user.
    • Returned only during creation.
    • Type: string
  • updated_at
    • The date and time the user was last updated, or null if never updated.
    • Type: string, nullable
  • username
    • The full username of the created user.
    • Type: string
    • Always present.

List Users​

Returns a list of all users in the company.

GET /api/customer_usage/v1/management/users

Request Parameters

  • page
    • page={page_number}
    • Return a specific page.
    • Optional
  • size
    • size={page_size}
    • The number of users to return per page.
    • Optional

Response

{
  "rl": {
    "page": {
      "current_page": 1,
      "next": "/api/customer_usage/v1/management/users?size=5&page=2",
      "previous": null,
      "total_pages": 3,
      "total_records": 11
    },
    "users": [
      {
        "created_at": "2024-07-26T09:09:46+0000",
        "description": "User description",
        "email_addresses": [
          "user@example.com"
        ],
        "enabled": true,
        "updated_at": null,
        "username": "u/company/user/1234"
      },
      ...
    ]
  }
}

Response Fields

  • page
    • current_page
      • The current page number.
      • Type: integer
      • Always present.
    • next
      • The URL for the next page, or null if there is no next page.
      • Type: string, nullable
      • Always present.
    • previous
      • The URL for the previous page, or null if there is no previous page.
      • Type: string, nullable
      • Always present.
    • total_pages
      • The total number of pages.
      • Type: integer
      • Always present.
    • total_records
      • The total number of records.
      • Type: integer
      • Always present.
  • users[]
    • The list of users.
    • Type: array[object]
    • Always present.
    • users[].created_at
      • The date and time when the user was created.
      • Type: string
      • Always present.
    • users[].description
      • The user description.
      • Type: string
      • Optional.
    • users[].email_addresses[]
      • The list of email addresses associated with the user.
      • Type: array[string]
      • Always present.
    • users[].enabled
      • Whether the user is currently enabled.
      • Type: boolean
      • Always present.
    • users[].updated_at
      • The date and time the user was last updated, or null if never updated.
      • Type: string, nullable
      • Always present.
    • users[].username
      • The full username of the created user.
      • Type: string
      • Always present.

Retrieve User​

GET /api/customer_usage/v1/management/users/{username}

{username} must be base64-encoded.

Response

{
  "rl": {
    "created_at": "2025-10-15T05:21:38+0000",
    "description": "Test user",
    "email_addresses": [
      "self.service@test.com"
    ],
    "enabled": true,
    "updated_at": null,
    "username": "u/company/username"
  }
}

Response Fields

  • created_at
    • The date and time when the user was created.
    • Type: string
    • Always present.
  • description
    • The user description.
    • Type: string
    • Optional.
  • email_addresses[]
    • The list of email addresses associated with the user.
    • Type: array[string]
    • Always present.
  • enabled
    • Whether the user is currently enabled.
    • Type: boolean
    • Always present.
  • updated_at
    • The date and time the user was last updated, or null if never updated.
    • Type: string, nullable
    • Always present.
  • username
    • The full username of the created user.
    • Type: string
    • Always present.

Update User​

Updates an existing user. All fields are optional.

PUT /api/customer_usage/v1/management/users/{username}

{username} must be base64-encoded.

Request

{
  "description": "Updated user for integration testing",
  "email_addresses": [
    "self.service@test.com",
    "secondary.contact@test.com"
  ],
  "enabled": false
}

Request Fields

Any of the fields from the Retrieve User response can be updated.

Response

{
  "rl": {
    "created_at": "2025-10-15T05:21:38+0000",
    "description": "Updated user for integration testing",
    "email_addresses": [
      "self.service@test.com",
      "secondary.contact@test.com"
    ],
    "enabled": false,
    "updated_at": "2025-10-15T05:28:57+0000",
    "username": "u/neworg/selfservice1234"
  }
}

Reset Password​

Resets the user's password.

PUT /api/customer_usage/v1/management/users/{username}/password-reset
  • {username} must be base64-encoded.
  • old_password_expiration_date is optional. If not provided, the password rotation grace period defaults to 1 hour from the time of the request.

Request

{
  "old_password_expiration_date": "2025-11-01T00:00:00Z"
}

Response

{
  "rl": {
    "password": "n3wp4ssw0rd"
  }
}

Licenses​

List Licenses​

Returns a list of all licenses for the company.

GET /api/customer_usage/v1/management/licenses

Request Parameters

  • page
    • page={page_number}
    • Return a specific page.
    • Optional
  • size
    • size={page_size}
    • The number of licenses to return per page.
    • Optional

Response

{
  "rl": {
    "licenses": [
      {
        "available_limit": 10000,
        "created_at": "2025-09-30T08:54:09+0000",
        "end_date": "2026-09-30",
        "id": 6427,
        "is_unlimited": false,
        "limit": 10000,
        "limit_type": "DAILY",
        "products": [
          "TCA-0314"
        ],
        "start_date": "2025-09-30",
        "strain": "PRODUCTS",
        "type": "ACTIVE",
        "updated_at": "2025-09-30T09:03:41+0000"
      },
      ...
    ],
    "page": {
      "current_page": 1,
      "next": null,
      "previous": null,
      "total_pages": 1,
      "total_records": 2
    }
  }
}

Response Fields

Response Fields

  • licenses[]

    • A list of license objects returned for the company.

    • licenses[].available_limit

      • The available limit for the license.
      • Optional

    • licenses[].created_at

      • The date and time the license was created.
      • Optional

    • licenses[].end_date

      • The end date of the license.
      • Optional

    • licenses[].id

      • The ID of the license.
      • Optional

    • licenses[].is_unlimited

      • Whether the license is unlimited.
      • Optional

    • licenses[].limit

      • The limit of the license.
      • Optional

    • licenses[].limit_type

      • The limit type of the license.
      • Optional

    • licenses[].products[]

      • The products associated with the license.
      • Optional

    • licenses[].start_date

      • The start date of the license.
      • Optional

    • licenses[].strain

      • The strain of the license. Can be either PRODUCTS or BUNDLE.
      • Optional

    • licenses[].type

      • The type of the license.
      • Optional

    • licenses[].updated_at

      • The date and time the license was updated.
      • Optional

  • page.current_page

    • The current page number of results.
    • Optional

  • page.next

    • The URL of the next page of results, or null if there is no next page.
    • Optional

  • page.previous

    • The URL of the previous page of results, or null if there is no previous page.
    • Optional

  • page.total_pages

    • The total number of pages available.
    • Optional

  • page.total_records

    • The total number of records across all pages.
    • Optional

Limits​

Create Limit​

Creates a new limit.

POST /api/customer_usage/v1/management/limits

Request Parameters

  • license_id
    • license_id={license_id}
    • The ID of the license to create the limit for.
    • Required
  • is_unlimited
    • is_unlimited={is_unlimited}
    • Whether the limit is unlimited. Mutually exclusive with limit, unless is_unlimited is set to false
    • Optional
  • limit
    • limit={limit}
    • The limit to set. Mutually exclusive with is_unlimited, unless is_unlimited is set to false
    • Optional
  • usernames
    • usernames={usernames}
    • The usernames to set the limit for.
    • Required
{
  "license_id": 6427,
  "is_unlimited": false,
  "limit": 10000,
  "usernames": ["u/company/user"]
}

Response

{
  "rl": {
    "id": 20939,
    "license_id": 6427,
    "is_unlimited": false,
    "limit": 10000,
    "usernames": [
      "u/company/user"
    ],
    "created_at": "2025-10-15T05:51:46+0000",
    "updated_at": null
  }
}

Response Fields

  • id
    • The unique ID of the created limit.
    • Always present.
  • license_id
    • The ID of the license the limit belongs to.
    • Required.
  • is_unlimited
    • Whether the limit is unlimited.
      Optional.
  • limit
    • The numeric value of the limit, if not unlimited.
      Optional.
  • usernames[]
    • List of usernames the limit applies to.
      Required.
  • created_at
    • Date and time when the limit was created.
    • Always present.
  • updated_at
    • Date and time when the limit was last updated, or null if never updated.
    • Optional.

Read License Limits​

Returns a list of limits created for a specific license.

GET /api/customer_usage/v1/management/licenses/{strain}/{license_id}/limits

Request Parameters

  • strain
    • License strain. Can be either PRODUCTS or BUNDLE. license_id can repeat for different strains.
    • Required
  • license_id
    • license_id={license_id}
    • The ID of the license to read the limits for. Must be considered in combination with strain, as a license with the ID 1234 can exist for both PRODUCTS and BUNDLE strains.
    • Required
  • page
    • page={page_number}
    • Return a specific page.
    • Optional
  • size
    • size={page_size}
    • The number of limits to return per page.
    • Optional

Response

{
  "rl": {
    "limits": [
      {
        "created_at": "2025-10-15T05:51:46+0000",
        "id": 20939,
        "is_unlimited": false,
        "license_id": 6427,
        "limit": 10000,
        "updated_at": null,
        "usernames": [
          "u/company/user"
        ],
        "strain": "PRODUCTS" 
      },
      {
        "created_at": "2025-10-15T05:51:46+0000",
        "id": 20940,
        "is_unlimited": false,
        "license_id": 6428,
        "limit": 10000,
        "updated_at": null,
        "usernames": [
          "u/company/user"
        ],
        "strain": "BUNDLE"
      }
    ],
    "page": {
      "current_page": 1,
      "next": null,
      "previous": null,
      "total_pages": 1,
      "total_records": 1
    }
  }
}

Read User Limits​

Returns a list of limits created for a specific user.

GET /api/customer_usage/v1/management/users/{username}/limits

{username} must be base64-encoded.

Response

{
  "rl": {
    "limits": [
      {
        "created_at": "2025-10-15T05:51:46+0000",
        "id": 20939,
        "is_unlimited": false,
        "license_id": 6427,
        "limit": 10000,
        "updated_at": null,
        "usernames": [
          "u/company/user"
        ],
        "strain": "PRODUCTS"
      },
      {
        "created_at": "2025-10-15T05:51:46+0000",
        "id": 20940,
        "is_unlimited": false,
        "license_id": 6427,
        "limit": 10000,
        "updated_at": null,
        "usernames": [
          "u/company/user"
        ],
        "strain": "BUNDLE"
      }
    ],
    "page": {
      "current_page": 1,
      "next": null,
      "previous": null,
      "total_pages": 1,
      "total_records": 1
    }
  }
}

Response Fields

  • limits[] A list of limits created for the specified user. Each limit object contains the following fields:
    • limits[].id The unique ID of the limit. Optional
    • limits[].license_id The ID of the license this limit is associated with. Optional
    • limits[].is_unlimited Indicates whether the limit is unlimited. Optional
    • limits[].limit The numeric value of the limit, if not unlimited. Optional
    • limits[].usernames[] A list of usernames this limit applies to. Optional
    • limits[].created_at The date and time the limit was created. Optional
    • limits[].updated_at The date and time the limit was last updated, or null if never updated. Optional
    • limits[].strain The strain of the license. Can be either PRODUCTS or BUNDLE. Optional
  • page.current_page The current page number of the results. Optional
  • page.next The URL of the next page of results, or null if there is no next page. Optional
  • page.previous The URL of the previous page of results, or null if there is no previous page. Optional
  • page.total_pages The total number of pages available. Optional
  • page.total_records The total number of records across all pages. Optional

Update Limit​

Updates an existing limit.

PUT /api/customer_usage/v1/management/limits/{limit_id}

Request

  • is_unlimited
    • is_unlimited={is_unlimited}
    • Whether the limit is unlimited.
    • Optional
  • limit
    • limit={limit}
    • The limit to set.
    • Optional
  • usernames
    • usernames={usernames}
    • The usernames to set the limit for.
    • Optional
{
  "is_unlimited": false,
  "limit": 1000,
  "usernames": ["u/company/user", "u/company/user2"]
}

Response

{
  "rl": {
    "created_at": "2025-10-15T05:51:46+0000",
    "id": 20939,
    "is_unlimited": false,
    "license_id": 6427,
    "limit": 1000,
    "updated_at": "2025-10-15T06:05:14+0000",
    "usernames": [
      "u/company/user",
      "u/company/user2"
    ]
  }
}

Response Fields

  • id The unique ID of the limit. Always present.
  • license_id The ID of the license this limit belongs to. Always present.
  • is_unlimited Indicates whether the limit is unlimited. Optional.
  • limit The numeric value of the limit, if not unlimited. Optional.
  • usernames[] The usernames this limit applies to. Optional.
  • created_at The date and time when the limit was created. Always present.
  • updated_at The date and time when the limit was last updated, or null if it hasn’t been updated yet. Optional.

Delete Limit​

Deletes a limit.

DELETE /api/customer_usage/v1/management/limits/{limit_id}

Path Parameters

  • limit_id
    The ID of the limit to delete.
    Required

Response 204 No Content

Usage and Monitoring​

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.

Daily Usage​

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.

View OpenAPI Specification 
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.

View OpenAPI Specification 
GET /api/customer_usage/v1/usage/company/daily

Request Parameters​

  • user
    • user=u/company/user
    • Return usage for the specified user. If not specified, the usage for the current user is returned.
    • Available for: User endpoint only (/api/customer_usage/v1/usage/daily)
    • Optional
  • 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​

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).

View OpenAPI Specification 
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).

View OpenAPI Specification 
GET /api/customer_usage/v1/usage/company/monthly

Request Parameters​

  • user
    • user=u/company/user
    • Return usage for the specified user. The user must belong to the same company as the authenticated user. If not specified, the usage for the current user is returned.
    • Available for: User endpoint only (/api/customer_usage/v1/usage/monthly)
    • Optional
  • 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​

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.

View OpenAPI Specification 
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.

View OpenAPI Specification 
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
            }
        ]
    }
}

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.

View OpenAPI Specification 
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
    }
}

Quota Limits​

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 thefree_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.

View OpenAPI Specification 
GET /api/customer_usage/v1/limits

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.

View OpenAPI Specification 
GET /api/customer_usage/v1/limits/company

Request Parameters​

  • user
    • user=u/company/user
    • Return limits for the specified user. The user must belong to the same company as the authenticated user. If not specified, the limits for the current user are returned.
    • Available for: User endpoint only (/api/customer_usage/v1/limits)
    • Optional
  • 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"
                        }
                    }
                ]
            }
            ...
        ]
    }
}

Email Alerting Configuration​

The Email Alerting Configuration service allows users to set up automated email notifications based on usage thresholds for specific products. By configuring alerts for selected product IDs, users can receive timely updates when their daily, monthly, or total usage exceeds defined percentage thresholds. This ensures better visibility and control over product consumption. Alerts are sent to a customizable list of email recipients, who may also opt out of future notifications via an unsubscribe link provided in each alert.

List Existing Alerts​

This query returns a list of currently stored alert configurations.

View OpenAPI Specification 
GET /api/customer_usage/v1/alerts

Response Format​

JSON

{
    "rl": {
        "alerts": [
            {
                "emails": [
                    "user@example.com"
                ],
                "enabled": true,
                "product_id": "TCA-0101",
                "thresholds": [50, 100]
            },
            ...
        ]
    }
}

Create/Update Existing Alert​

This query creates a new alert configuration or updates an existing one for the same product ID.

View OpenAPI Specification 
POST /api/customer_usage/v1/alert

Request format​

JSON

{
    "rl": {
        "alert": {
            "product_id": "TCA-0101",
            "emails": [
                "user@example.com"
            ],
            "thresholds": [50, 100],
            "enabled": true
        }
    }
}

An alert contains a product_id, a list of recipients, a boolean enabled flag, and a list of thresholds. Following product_id values are supported:

TCA-0101, TCA-0103, TCA-0104, TCA-0105, TCA-0106,
TCA-0201, TCA-0202, TCA-0203, TCA-0204, TCA-0205, TCA-0206, TCA-0207, TCA-0207-URL,
TCA-0301, TCA-0302, TCA-0303, TCA-0305, TCA-0319, TCA-0320, TCA-0321,
TCA-0401, TCA-0402, TCA-0403, TCA-0404, TCA-0405, TCA-0406, TCA-0407,
TCA-0501, TCA-0502, TCA-0503,
TCAI-0001, TCAI-0011, TCAI-0106, TCAI-0320

thresholds may contain any number of integer percentage values from 1 to 100 (inclusive). For each enabled alert, the service will email all listed recipients whenever the usage for the corresponding product_id crosses any configured threshold.

Successful alert creation or update returns an empty 200 OK response.

Individual recipients may unsubscribe from future alerts by following the unsubscribe link included in each notification email.

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