Consent Manager

  • Your Privacy

  • Strictly Necessary Cookies

  • Performance Cookies

  • Targeting Cookies

  • Functional Cookies

Your Privacy

When you visit any website, it may store or retrieve information on your browser, mostly in the form of cookies. This information might be about you, your preferences or your device and is mostly used to make the site work as you expect it to. The information does not usually directly identify you, but it can give you a more personalized web experience. Because we respect your right to privacy, you can choose not to allow some types of cookies. Click on the different category headings to find out more and change our default settings. However, blocking some types of cookies may impact your experience of the site and the services we are able to offer. For more information on the information we collect and how we use it see the Website Privacy Statement.

Strictly Necessary Cookies

Always Active

These cookies are necessary for the website to function and cannot be switched off in our systems. They are usually only set in response to actions made by you which amount to a request for services, such as setting your privacy preferences, logging in or filling in forms. You can set your browser to block or alert you about these cookies, but some parts of the site will not then work. These cookies do not store any personally identifiable information.

Performance Cookies

Off On

These cookies allow us to count visits and traffic sources so we can measure and improve the performance of our site. They help us to know which pages are the most and least popular and see how visitors move around the site. All information these cookies collect is aggregated and therefore anonymous. If you do not allow these cookies we will not know when you have visited our site, and will not be able to monitor its performance.

Targeting Cookies

Off On

These cookies may be set through our site by our advertising partners. They may be used by those companies to build a profile of your interests and show you relevant adverts on other sites. They do not store directly personal information, but are based on uniquely identifying your browser and internet device. If you do not allow these cookies, you will experience less targeted advertising.

Functional Cookies

These cookies enable the website to provide enhanced functionality and personalization. They may be set by us or by third party providers whose services we have added to our pages. If you do not allow these cookies then some or all of these services may not function properly.

Your Privacy [`dialog closed`]

By continuing to use our website, you acknowledge the use of cookies. Privacy Statement | Change Settings

Cookies allow us to optimise your use of our website. We also use third-party cookies for advertising and analytics. Please read our Privacy Statement and Website Privacy Statement for more information on how we use cookies.

DEVELOPER REFERENCE

Search Results

×Clear
  • Overview

    • Welcome
    • Authentication
    • Account group context
    • Response formats
    • Time ranges
    • Response status codes
    • Rate limits
    • Pagination
    • Change policy
    • API change summary
  • Instant tests

    • Instant test
    • Instant test rerun
  • Tests

    • Test list
    • Test list by type
    • Test details
    • Test metadata
    • Creating a test
    • Updating a test
    • Deleting a test
    • Saved events
    • Path vis interface group list
    • Creating path vis interface group
    • Updating path vis interface group
    • Deleting path vis interface group
  • Test Data

    • (Network) End-to-End metrics
    • (Network) Path visualization
    • (Network) Detailed path trace
    • (Network) BGP metrics
    • (Network) BGP route information
    • (Web) HTTP server
    • (Web) Page load
    • (Web) Page load component detail
    • (Web) Web Transactions
    • (Web) Web Transaction detail
    • (Web) Web Transaction component detail
    • (Web) FTP server
    • (DNS) Domain trace
    • (DNS) Server metrics
    • (DNS) DNSSEC
    • (Voice) SIP server
    • (Voice) RTP stream
  • Credentials

    • Credential list
    • Credential details
    • Creating a credential
    • Updating a credential
    • Deleting a credential
  • Endpoint Agents

    • Listing all agents
    • Getting an agent by id
    • Updating an agent
    • Enabling an agent
    • Disabling an agent
    • Transferring an agent
    • Deleting an agent
  • Endpoint Data

    • Endpoint user session list
    • Endpoint user session details
    • Endpoint web pages list
    • Endpoint web page details
    • Endpoint network sessions list
    • Endpoint network topology list
    • Endpoint network topology details
    • Endpoint data filtering
    • Endpoint networks
  • Endpoint Tests

    • Scheduled Test List
    • Scheduled Test List by Type
    • Scheduled Test Details
    • Scheduled Test Metadata
    • Creating a Scheduled Test
    • Automated Session Test List
    • Automated Session Test Details
    • Automated Session Test Metadata
    • Creating an Automated Session Test
  • Endpoint Test Data

    • Scheduled Tests (Network) End-to-End metrics
    • Scheduled Tests (Network) Path visualization
    • Scheduled Tests (Network) Detailed path trace
    • Scheduled Tests (Web) HTTP server
    • Automated Session Tests End-to-End metrics
    • Automated Session Tests Path visualization
    • Automated Session Tests Detailed path trace
  • Endpoint Instant Tests

    • Creating instant test
    • Rerunning instant test
  • Snapshots

    • Create a new snapshot
  • Agents & Monitors

    • Agent list
    • Agent detail
    • Updating an agent
    • Deleting an Agent
    • Agent cluster - Creating
    • Agent cluster - Adding members
    • Agent cluster - Removing members
    • Agent cluster - Converting to an agent
    • BGP Monitor list
    • Agent Notification Rules
    • Agent Notification Rule Detail
    • Agent Proxies List
  • Alerts & Notifications

    • Active alerts
    • Alert detail
    • Alert rules
    • Alert rule detail
    • Alert rule metadata
    • Creating an alert rule
    • Updating an alert rule
    • Deleting an alert rule
    • Alert notification integrations
    • Alert suppression windows
    • Alert suppression window detail
    • Creating an alert suppression window
    • Updating an alert suppression window
    • Deleting an alert suppression window
    • Creating an advanced Alert Rule
  • Labels

    • Labels list
    • Labels list by type
    • Label details
    • Label details (by label type)
    • Creating a label
    • Updating a label
    • Deleting a label
  • Dashboards

    • Dashboards list
    • Dashboards detail
    • Dashboard data
    • Deleting a dashboard
    • Dashboard snapshots list
    • Dashboards snapshot detail
    • Dashboard snapshot data
    • Deleting a dashboard snapshot
  • Reports

    • Reports list
    • Report detail
    • Report data
    • Deleting a report
    • Report snapshots list
    • Report snapshot detail
    • Report snapshot data
    • Deleting a report snapshot
  • Administrative endpoints

    • Account group list
    • Account group detail
    • Creating an account group
    • Updating an account group
    • Deleting an account group
    • User list
    • User detail
    • Adding a user
    • Updating a user
    • Deleting a user
    • Role list
    • Role detail
    • Creating a role
    • Updating a role
    • Permission list
    • Activity log
    • Obtaining usage quota
    • Updating usage quotas
  • Usage

    • Obtaining usage details
    • Usage metadata

  • Showing APIv6  |  APIv7 (preview)

  • Product Documentation
  • Customer Success Center
  • Public GitHub Repository

Try ThousandEyes Now! Sign Up

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 {email}:{authToken}

Response

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

Header

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, "endpointAgentsEssentialsIncluded": 10, "endpointAgentsEmbeddedIncluded": 11 }, "cloudUnitsUsed": 8500489, "cloudUnitsProjected": 20993812, "cloudUnitsNextBillingPeriod": 25123456, "enterpriseUnitsUsed": 79640902, "enterpriseUnitsProjected": 108016317, "enterpriseUnitsNextBillingPeriod": 0, "endpointAgentsUsed": 42, "endpointAgentsEssentialsUsed": 5, "endpointAgentsEmbeddedUsed": 6, "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 }, [...] ], "endpointAgentsEssentials": [ { "aid": 7625, "accountGroupName": "Support", "endpointAgentsEssentialsUsed": 1 }, { "aid": 315, "accountGroupName": "Documentation", "endpointAgentsEssentialsUsed": 4 }, [...] ], "endpointAgentsEmbedded": [ { "aid": 7625, "accountGroupName": "Support", "endpointAgentsEmbeddedUsed": 1 }, { "aid": 315, "accountGroupName": "Documentation", "endpointAgentsEmbeddedUsed": 5 }, [...] ], "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.
quotaendpointAgentsEssentialsIncludedinteger"endpointAgentsEssentialsIncluded": 10Monthly number of endpoint agents essentials allocated, as part of the contract.
quotaendpointAgentsEmbeddedIncludedinteger"endpointAgentsEmbeddedIncluded": 11Monthly number of endpoint agents embedded 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/aendpointAgentsEssentialsUsedinteger"endpointAgentsEssentialsUsed": 5Number of endpoint agents essentials 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/aendpointAgentsEmbeddedUsedinteger"endpointAgentsEmbeddedUsed": 6Number of endpoint agents embedded 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/aendpointAgentsEssentialsarray of endpointAgentsEssentials objectssee individual fieldsEndpoint agents essentials used by account group.
endpointAgentEssentialsaidinteger"aid": 7625Unique ID of the account group owning the endpoint agents essentials
endpointAgentEssentialsaccountGroupNamestring"accountGroupName": "Support"Name of the account group which owns the endpoint agents essentials
endpointAgentEssentialsendpointAgentsEssentialsUsedinteger"endpointAgentsEssentialsUsed": 1Number of endpoint agents essentials owned by the specific account group in the usage period.
n/aendpointAgentsEmbeddedarray of endpointAgentsEmbedded objectssee individual fieldsEndpoint agents embedded used by account group.
endpointAgentEmbeddedaidinteger"aid": 7625Unique ID of the account group owning the endpoint agents Embedded
endpointAgentEmbeddedaccountGroupNamestring"accountGroupName": "Support"Name of the account group which owns the endpoint agents Embedded
endpointAgentEmbeddedendpointAgentsEmbeddedUsedinteger"endpointAgentsEssentialsUsed": 1Number of endpoint agents Embedded 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.
© 2023 ThousandEyes. All rights reserved.