Usage

GET /v6/usage Obtaining usage details

This endpoint returns usage for the current period. This endpoint requires the View Billing permission (a management permission), and provides visibility across all account groups within the organization. For users who have access to view billing in multiple organizations, query the endpoint using an aid querystring parameter (see optional parameters, below) from each organization.

Billing information (for past months) is not available via this endpoint; this will be implemented as a separate endpoint.

Optional Parameters

  • format=json|xml optional, specifies the format of output requested. See Output Formats for more information
  • aid={aid} optional, changes the organization context of the current request. If an invalid account group ID is specified as a parameter, the response will come back as an HTTP/400 error. When querying the /usage endpoint, the aid parameter is used to provide usage details for the organization to which the account group ID belongs. The output always provides visibility across all account groups within the specified organization.

Request

  • There is no request body for this request.

Example

$ curl https://api.thousandeyes.com/v6/usage.json \ -u noreply@thousandeyes.com:g351mw5xqhvkmh1vq6zfm51c62wyzib2

Response

Sends back detailed usage information about the organization. Users in roles with insufficient permissions will receive an HTTP/403 response.

HTTP/1.1 200 OK Date: Fri, 17 Jan 2020 17:59:14 GMT Content-Type: application/json;charset=UTF-8 Transfer-Encoding: chunked Connection: keep-alive Vary: Accept-Encoding X-Server-Name: r1grs Cache-Control: no-store X-Organization-Rate-Limit-Limit: 1000 X-Organization-Rate-Limit-Remaining: 999 X-Organization-Rate-Limit-Reset: 1579284000 Strict-Transport-Security: max-age=15724800; includeSubDomains Strict-Transport-Security: max-age=31536000 X-Content-Type-Options: nosniff

Body

{ "usage": { "quota": { "monthStart": "2020-01-05 08:00:00", "monthEnd": "2020-02-05 08:00:00", "cloudUnitsIncluded": 4320000000, "enterpriseAgentsIncluded": 0, "endpointAgentsIncluded": 200 }, "cloudUnitsUsed": 8500489, "cloudUnitsProjected": 20993812, "cloudUnitsNextBillingPeriod": 25123456, "enterpriseUnitsUsed": 79640902, "enterpriseUnitsProjected": 108016317, "enterpriseUnitsNextBillingPeriod": 0, "endpointAgentsUsed": 42, "enterpriseAgentsUsed": 58, "tests": [ { "aid": 315, "testId": 1158, "accountGroupName": "Documentation", "testName": "https://app.thousandeyes.com", "testType": "Web - Page Load", "cloudUnitsUsed": 140540, "cloudUnitsProjected": 340674 }, { "aid": 315, "testId": 1159, "accountGroupName": "Documentation", "testName": "https://support.thousandeyes.com", "testType": "Web - HTTP Server", "cloudUnitsUsed": 64390, "cloudUnitsProjected": 164457 }, [...] ], "endpointAgents": [ { "aid": 7625, "accountGroupName": "Support", "endpointAgentsUsed": 22 }, { "aid": 315, "accountGroupName": "Documentation", "endpointAgentsUsed": 14 }, [...] ], "enterpriseAgents": [ { "aid": 7625, "accountGroupName": "Support", "enterpriseAgentsUsed": 7 }, { "aid": 315, "accountGroupName": "Documentation", "enterpriseAgentsUsed": 1 }, [...] ], "enterpriseAgentUnits": [ { "aid": 7625, "agentId": 121404, "accountGroupName": "Support", "agentName": "TEVA-test-agent", "enterpriseUnitsUsed": 599878, "enterpriseUnitsProjected": 597808, "vagentId": 123456 }, { "aid": 315, "agentId": 121404, "accountGroupName": "Documentation", "agentName": "lab-physical-appliance-1", "enterpriseUnitsUsed": 597123, "enterpriseUnitsProjected": 597808, "vagentId": 789 }, [...] ] } }

For more information on our HTTP response status codes, see the response status codes documentation.

Usage metadata

Usage metadata is used in the /usage endpoint. Field types are shown in the table below, along with information about each field returned.

Fields are listed (as they appear in the data) in the table below. Where a complex object is used, the field will be prefixed with the object name.

ObjectFieldData TypeExampleNotes
quotamonthStartdateTime"monthStart": "2016-04-28 17:00:00 PDT"Beginning of usage period in YYYY-mm-dd HH:MM:SS format. As with other endpoints, dateTime values are shown in UTC.
quotamonthEnddateTime"monthEnd": "2016-04-28 17:00:00 PDT"End of usage period in YYYY-mm-dd HH:MM:SS format. As with other endpoints, dateTime values are shown in UTC.
quotacloudUnitsIncludedinteger"cloudUnitsIncluded": 4320000000Monthly number of cloud units allocated, as part of the contract.
quotaendpointAgentsIncludedinteger"endpointAgentsIncluded": 200Monthly number of endpoint agents allocated, as part of the contract.
quotaenterpriseAgentsIncludedinteger"enterpriseAgentsIncluded": 25Monthly number of enterprise agents allocated, as part of the contract. Returns non-zero value only for organizations with legacy billing.
n/acloudUnitsUsedinteger"cloudUnitsUsed": 8500489Number of cloud units consumed thus far in the usage period.
n/acloudUnitsProjectedinteger"cloudUnitsProjected": 8500489Number of cloud units projected in the current usage period, based on units consumed to date and configuration of enabled tests. This value is updated hourly.
n/acloudUnitsNextBillingPeriodinteger"cloudUnitsNextBillingPeriod": 8500489Number of cloud units projected in the upcoming usage period, based on configuration of enabled tests. This value is updated hourly.
n/aenterpriseUnitsUsedinteger"enterpriseUnitsUsed": 8500489Number of enterprise units consumed thus far in the usage period. Returns non-zero value only for organizations with metered billing.
n/aenterpriseUnitsProjectedinteger"enterpriseUnitsProjected": 8500489Number of enterprise units projected in the current usage period, based on units consumed to date and configuration of enabled tests. This value is updated hourly. Returns non-zero value only for organizations with metered billing.
n/aenterpriseUnitsNextBillingPeriodinteger"enterpriseUnitsNextBillingPeriod": 8500489Number of enterprise units projected in the upcoming usage period, based on configuration of enabled tests. This value is updated hourly. Returns non-zero value only for organizations with metered billing.
n/aendpointAgentsUsedinteger"endpointAgentsUsed": 42Number of endpoint agents used thus far in the current usage period. This number is calculated by taking the maximum number of agents enabled for any one-hour period in the usage period. Disabled agents are excluded from this calculation.
n/aenterpriseAgentsUsedinteger"enterpriseAgentsUsed": 8Number of enterprise agents used thus far in the current usage period. This number is calculated by taking the maximum number of agents enabled for any one-hour period in the usage period. Disabled agents are excluded from this calculation.
n/atestsarray of test objectssee individual fieldsTest-by-test breakdown of unit consumption in the current monthly period; Each entry includes both current and projected usage.
testaidinteger"aid": 1234Unique ID of the account group which owns the test
testaccountGroupNamestring"accountGroupName": "Support"Name of the account group which owns the test
testtestIdinteger"testId": 26030Unique ID of the test generating usage
testtestNamestring"testName": "my test name"Name of the test generating usage
testtestTypestring"testType": "Web - HTTP Server"Type of test generating usage. Note that this is a friendly testType entry (so it shouldn’t be parsed to discover the correct endpoint to query for configuration details).
testcloudUnitsUsedinteger"cloudUnitsUsed": 8500489Number of cloud units consumed thus far by the test in the usage period.
testcloudUnitsProjectedinteger"cloudUnitsProjected": 253012Number of cloud units projected to be consumed by the test in the usage period, based on units consumed to date and configuration of the test. This value is updated hourly. New tests have no cloudUnitsProjected parameter until projection is calculated.
n/aendpointAgentsarray of endpointAgent objectssee individual fieldsEndpoint agents used by account group.
endpointAgentaidinteger"aid": 1234Unique ID of the account group owning the endpoint agents
endpointAgentaccountGroupNamestring"accountGroupName": "sample account group name"Name of the account group which owns the endpoint agents
endpointAgentendpointAgentsUsedinteger"endpointAgentsUsed": 7Number of endpoint agents owned by the specific account group in the usage period.
n/aenterpriseAgentsarray of enterpriseAgent objectssee individual fieldsEnterprise agents used by account group.
n/aenterpriseAgentUnitsarray of enterpriseAgentUnit objectssee individual fieldsAgent-by-agent breakdown of enterprise units consumed in current monthly period; Each entry includes both current and projected usage. Returns non-zero value only for organizations with metered billing.
enterpriseAgentaidinteger"aid": 1234Unique ID of the account group owning the enterprise agents
enterpriseAgentaccountGroupNamestring"accountGroupName": "sample account group name"Name of the account group which owns the enterprise agents
enterpriseAgententerpriseAgentsUsedinteger"enterpriseAgentsUsed": 7Number of enterprise agents owned by the specific account group in the usage period.