{"type":"api","title":"Get usage information for the last month","meta":{"id":"/apps/pubhub/media/000-v7-apis/5b3454a4300b838cc17f7b2cdc0690fdd15058d5/8338b1ff-e9bc-34cf-ba50-5477b3cc7c1a","info":{"description":"\nThese usage endpoints define the following operations:\n\n* **Usage**: Retrieve usage data for the specified time period (default is one month).\n \n * Users must have the `View organization usage` permission to access this endpoint.\n * This operation offers visibility across all account groups within the organization.\n * Users with `View organization usage` permission in multiple organizations should query the operation with the `aid` query string parameter (see optional parameters) for each organization.\n\n* **Quotas**: Obtain organization and account usage quotas. Additionally, users with the appropriate permissions can create, update, or delete these quotas.\n \n * Users must have the necessary permissions to perform quota-related actions.\n\nRefer to the Usage API operations for detailed usage instructions and optional parameters.\n","title":"Usage API","version":"7.0.34"},"security":[{"BearerAuth":[]}],"tags":[{"description":"Usage GET Operation","name":"Usage"},{"description":"Quota CRUD Operation","name":"Quotas"}],"externalDocs":{"description":"Find out more about the usage model","url":"https://docs.thousandeyes.com/product-documentation/user-management/usage-and-billing/how-unit-consumption-works#what-is-the-projected-usage"},"openapi":"3.0.1","servers":[{"description":"ThousandEyes API production URL","url":"https://api.thousandeyes.com/v7"}],"securitySchemes":{"BearerAuth":{"description":"Bearer authentication token","scheme":"bearer","type":"http"}}},"spec":{"description":"This operation returns usage for the current period. It provides visibility across all account groups within an organization. To access this endpoint, you need the `View Billing` permission (a management permission). If you have access to view billing in multiple organizations, query the endpoint using an `aid` querystring parameter (see optional parameters, below) from each organization.\n**Note:** Access to billing information older than one month is not supported by this endpoint.","operationId":"getUsage","parameters":[{"description":"A unique identifier associated with your account group. You can retrieve your `AccountGroupId` from the `/account-groups` endpoint. Note that you must be assigned to the target account group. Specifying this parameter without being assigned to the target account group will result in an error response.","in":"query","name":"aid","required":false,"schema":{"example":"1234","type":"string"}},{"description":"Expands the available resources. By default, no expansion takes place if the `expand` query parameter is not passed. For example, to expand the \"tests\" resource, pass the query '?expand=test'.","explode":false,"in":"query","name":"expand","required":false,"schema":{"example":["test"],"items":{"enum":["test","enterprise-agent","enterprise-agent-unit","endpoint-agent","endpoint-agent-essential","endpoint-agent-embedded"],"type":"string","$$ref":"#/components/schemas/ExpandUsageOptions"},"type":"array"},"style":"form"}],"responses":{"200":{"content":{"application/hal+json":{"schema":{"properties":{"usage":{"properties":{"quota":{"properties":{"monthStart":{"description":"Beginning of usage period in UTC (ISO date-time format).","example":"2020-01-05T08:00:00Z","format":"date-time","type":"string"},"monthEnd":{"description":"End of usage period in UTC (ISO date-time format)..","example":"2020-02-05T08:00:00Z","format":"date-time","type":"string"},"cloudUnitsIncluded":{"description":"Monthly number of cloud units allocated, as part of the contract.","example":4320000000,"format":"int64","type":"integer"},"deviceAgentsIncluded":{"description":"Number of device agents (connected devices product) allocated monthly, as specified in the contract.","example":100,"format":"int64","type":"integer"},"endpointAgentsIncluded":{"description":"Monthly number of endpoint agents allocated, as part of the contract.","example":200,"format":"int64","type":"integer"},"endpointAgentsEssentialsIncluded":{"description":"Monthly number of endpoint agents essentials allocated, as part of the contract.","example":10,"format":"int64","type":"integer"},"endpointAgentsEmbeddedIncluded":{"description":"Number of embedded endpoint agents allocated monthly, as specified in the contract.","example":10,"format":"int64","type":"integer"},"enterpriseAgentsIncluded":{"description":"Monthly number of enterprise agents allocated, as part of the contract. Returns non-zero value only for organizations with legacy billing.","example":25,"format":"int64","type":"integer"}},"type":"object","$$ref":"#/components/schemas/UsageQuota"},"cloudUnitsUsed":{"description":"Number of cloud units consumed thus far in the usage period.","example":8500489,"format":"int64","type":"integer"},"cloudUnitsProjected":{"description":"Number 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.","example":20993812,"format":"int64","type":"integer"},"cloudUnitsNextBillingPeriod":{"description":"Number of cloud units projected in the upcoming usage period, based on configuration of enabled tests. This value is updated hourly.","example":25123456,"format":"int64","type":"integer"},"enterpriseUnitsUsed":{"description":"Number of enterprise units consumed in the usage period. Returns non-zero value only for organizations with metered billing.","example":79640902,"format":"int64","type":"integer"},"enterpriseUnitsProjected":{"description":"Number 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.","example":108016317,"format":"int64","type":"integer"},"enterpriseUnitsNextBillingPeriod":{"description":"Projected number of enterprise units for the upcoming usage period, based on the configuration of enabled tests. This value is updated hourly and returns a non-zero value only for organizations with metered billing.","example":0,"format":"int64","type":"integer"},"connectedDevicesUnitsUsed":{"description":"Number of connected device units consumed in the usage period.","example":79640902,"format":"int64","type":"integer"},"connectedDevicesUnitsProjected":{"description":"Projected number of connected device units for the current usage period. This projection is based on the units consumed to date and the configuration of enabled tests. The value is updated hourly.","example":108016317,"format":"int64","type":"integer"},"connectedDevicesUnitsNextBillingPeriod":{"description":"Projected number of connected device units for the upcoming usage period. This projection is based on the configuration of enabled tests and is updated hourly.","example":0,"format":"int64","type":"integer"},"endpointAgentsUsed":{"description":"Number of endpoint agents used 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.","example":42,"format":"int64","type":"integer"},"endpointAgentsEssentialsUsed":{"description":"Number of endpoint agents essentials used 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.","example":5,"format":"int64","type":"integer"},"endpointAgentsEmbeddedUsed":{"description":"Number of embedded endpoint agents used 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.","example":5,"format":"int64","type":"integer"},"enterpriseAgentsUsed":{"description":"Number of enterprise agents used 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.","example":58,"format":"int64","type":"integer"},"enterpriseAgentUnits":{"description":"A breakdown of enterprise unit consumption for each agent during the current monthly period. Each entry provides data for both the current actual usage and the projected usage. Returns non-zero values for organizations with metered billing.","example":[{"aid":"1234","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"}],"items":{"properties":{"aid":{"description":"Unique identifier of the account group owning the enterprise agent units.","example":"1234","type":"string"},"accountGroupName":{"description":"Name of the account group which owns the enterprise agent units.","example":"Account A","type":"string"},"agentId":{"description":"Unique identifier of the enterprise agent generating usage.","type":"string"},"agentName":{"description":"Name of the enterprise agent generating usage.","type":"string"},"enterpriseUnitsUsed":{"description":"Number of enterprise agent units owned by the specific account group in the usage period.","format":"int64","type":"integer"},"enterpriseUnitsProjected":{"description":"Number 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.","format":"int64","type":"integer"},"vagentId":{"description":"Unique identifier of the virtual agent generating usage","type":"string"}},"type":"object","$$ref":"#/components/schemas/EnterpriseAgentUnits"},"type":"array"},"tests":{"description":"A breakdown of unit consumption for each test during the current monthly period. Each entry provides information about both the current actual usage and the projected usage.","example":[{"aid":"1234","testId":"1158","accountGroupName":"Documentation","testName":"https://app.thousandeyes.com","testType":"Web-Page Load","cloudUnitsUsed":14050,"cloudUnitsProjected":340674},{"aid":"12345","testId":"1159","accountGroupName":"Documentation","testName":"https://support.thousandeyes.com","testType":"Web - HTTP Server","cloudUnitsUsed":64390,"cloudUnitsProjected":164457}],"items":{"properties":{"aid":{"description":"Unique identifier of the account group which owns the test.","example":"1234","type":"string"},"accountGroupName":{"description":"Name of the account group which owns the test.","example":"Account A","type":"string"},"testId":{"description":"Unique identifier of the test generating usage.","type":"string"},"testName":{"description":"Name of the test generating usage.","type":"string"},"testType":{"description":"The type of test that generated the usage data. Note that this parameter provides a user-friendly description of the test type and should not be parsed to determine the endpoint for querying configuration details.","type":"string"},"cloudUnitsUsed":{"description":"Number of cloud units that the test has consumed in the usage period.","format":"int64","type":"integer"},"cloudUnitsProjected":{"description":"The estimated number of cloud units that the test is expected to consume during the usage period. This estimate is determined by considering the units consumed up to the current time and the test's configuration. It's important to note that this value is updated every hour. For new tests, the `cloudUnitsProjected` parameter is absent until the projection is calculated.","format":"int64","type":"integer"}},"type":"object","$$ref":"#/components/schemas/TestUsage"},"type":"array"},"endpointAgents":{"description":"Endpoint agents used by account group.","example":[{"aid":"1234","accountGroupName":"Support","endpointAgentsUsed":22},{"aid":"12345","accountGroupName":"Documentation","endpointAgentsUsed":14}],"items":{"properties":{"aid":{"description":"Unique identifier of the account group owning the endpoint agents.","example":"1234","type":"string"},"accountGroupName":{"description":"Name of the account group which owns the endpoint agents.","example":"Account A","type":"string"},"endpointAgentsUsed":{"description":"Number of endpoint agents owned by the specific account group in the usage period.","format":"int64","type":"integer"}},"type":"object","$$ref":"#/components/schemas/EndpointAgentsUsage"},"type":"array"},"endpointAgentsEssentials":{"description":"Endpoint agents essentials used by account group.","example":[{"aid":"1234","accountGroupName":"Support","endpointAgentsEssentialsUsed":2},{"aid":"12345","accountGroupName":"Documentation","endpointAgentsEssentialsUsed":3}],"items":{"properties":{"aid":{"description":"Unique identifier of the account group owning the endpoint agents essentials.","example":"1234","type":"string"},"accountGroupName":{"description":"Name of the account group which owns the endpoint agents essentials.","example":"Account A","type":"string"},"endpointAgentsEssentialsUsed":{"description":"Number of endpoint agents essentials owned by the specific account group in the usage period.","format":"int64","type":"integer"}},"type":"object","$$ref":"#/components/schemas/EndpointAgentsEssentials"},"type":"array"},"endpointAgentsEmbedded":{"description":"Endpoint agents embedded used by account group.","example":[{"aid":"1234","accountGroupName":"Support","endpointAgentsEmbeddedUsed":2},{"aid":"12345","accountGroupName":"Documentation","endpointAgentsEmbeddedUsed":3}],"items":{"properties":{"aid":{"description":"Unique identifier of the account group that owns the embedded endpoint agents.","example":"1234","type":"string"},"accountGroupName":{"description":"Name of the account group that owns the embedded endpoint agents.","example":"Account A","type":"string"},"endpointAgentsEmbeddedUsed":{"description":"Number of endpoint agents embedded owned by the specific account group in the usage period.","format":"int64","type":"integer"}},"type":"object","$$ref":"#/components/schemas/EndpointAgentsEmbedded"},"type":"array"},"enterpriseAgents":{"description":"Enterprise agents used by account group.","example":[{"aid":"1234","accountGroupName":"Support","enterpriseAgentsUsed":7},{"aid":"12345","accountGroupName":"Documentation","enterpriseAgentsUsed":1}],"items":{"properties":{"aid":{"description":"A unique identifier that specifies the account group that owns the enterprise agents.","example":"1234","type":"string"},"accountGroupName":{"description":"Name of the account group which owns the enterprise agents.","example":"Account A","type":"string"},"enterpriseAgentsUsed":{"description":"Number of enterprise agents owned by the specific account group in the usage period.","format":"int64","type":"integer"}},"type":"object","$$ref":"#/components/schemas/EnterpriseAgents"},"type":"array"}},"type":"object","$$ref":"#/components/schemas/UsageDetails"},"_links":{"description":"A links object containing the self link.","properties":{"self":{"description":"A hyperlink from the containing resource to a URI.","properties":{"href":{"description":"Its value is either a URI [RFC3986] or a URI template [RFC6570].","example":"https://api.thousandeyes.com/v7/link/to/resource/id","type":"string"},"templated":{"description":"Should be true when the link object's \"href\" property is a URI template.","type":"boolean"},"type":{"description":"Used as a hint to indicate the media type expected when dereferencing the target resource.","type":"string"},"deprecation":{"description":"Its presence indicates that the link is to be deprecated at a future date. Its value is a URL that should provide further information about the deprecation.","type":"string"},"name":{"description":"Its value may be used as a secondary key for selecting link objects that share the same relation type.","type":"string"},"profile":{"description":"A URI that hints about the profile of the target resource.","type":"string"},"title":{"description":"Intended for labelling the link with a human-readable identifier","type":"string"},"hreflang":{"description":"Indicates the language of the target resource","type":"string"}},"required":["href"],"type":"object","$$ref":"#/components/schemas/Link"}},"readOnly":true,"type":"object","$$ref":"#/components/schemas/SelfLinks"}},"type":"object","$$ref":"#/components/schemas/Usage"}}},"description":"OK"},"400":{"content":{"application/problem+json":{"example":{"type":"about:blank","title":"Request validation failed. There are invalid or missing fields","status":400,"detail":"Your request object contains invalid fields.","instance":"/v7","errors":[{"code":"AM-5432","field":"firstName","message":"firstName cannot have fancy characters"},{"code":"DASH-5622","field":"password","message":"Password cannot be blank"}]},"schema":{"properties":{"type":{"description":"A URI reference that identifies the problem type. When this member is not present, its value is assumed to be \"about:blank\".","type":"string"},"title":{"description":"A short, human-readable summary of the problem type.","type":"string"},"status":{"description":"The HTTP status code generated by the origin server for this occurrence of the problem.","type":"integer"},"detail":{"description":"A human-readable explanation specific to this occurrence of the problem.","type":"string"},"instance":{"description":"A URI reference that identifies the specific occurrence of the problem.","type":"string"},"errors":{"description":"(Optional) When multiple errors occur, the details for each error are listed.","items":{"properties":{"code":{"description":"(Optional) A unique error type/code that can be referenced in the documentation for further details.","type":"string"},"field":{"description":"Identifies the field that triggered this particular error.","type":"string"},"message":{"description":"A short, human-readable summary of the error.","type":"string"}},"type":"object","$$ref":"#/components/schemas/ValidationErrorItem"},"nullable":true,"type":"array"}},"type":"object","$$ref":"#/components/schemas/ValidationError"}}},"description":"Bad Request"},"401":{"content":{"application/problem+json":{"schema":{"properties":{"error":{"example":"invalid_token","type":"string"},"error_description":{"example":"Invalid access token","type":"string"}},"type":"object","$$ref":"#/components/schemas/UnauthorizedError"}}},"description":"Unauthorized"},"403":{"content":{"application/problem+json":{"schema":{"properties":{"type":{"description":"A URI reference that identifies the problem type. When this member is not present, its value is assumed to be \"about:blank\".","type":"string"},"title":{"description":"A short, human-readable summary of the problem type.","type":"string"},"status":{"description":"The HTTP status code generated by the origin server for this occurrence of the problem.","type":"integer"},"detail":{"description":"A human-readable explanation specific to this occurrence of the problem.","type":"string"},"instance":{"description":"A URI reference that identifies the specific occurrence of the problem.","type":"string"}},"type":"object","$$ref":"#/components/schemas/Error"}}},"description":"Insufficient permissions to query endpoint"},"404":{"content":{"application/problem+json":{"example":{"type":"about:blank","title":"URI Resource Not Found","status":404,"detail":"Details explaining if the 404 error is related to an invalid URI or a wrong ID","instance":"/v7"},"schema":{"properties":{"type":{"description":"A URI reference that identifies the problem type. When this member is not present, its value is assumed to be \"about:blank\".","type":"string"},"title":{"description":"A short, human-readable summary of the problem type.","type":"string"},"status":{"description":"The HTTP status code generated by the origin server for this occurrence of the problem.","type":"integer"},"detail":{"description":"A human-readable explanation specific to this occurrence of the problem.","type":"string"},"instance":{"description":"A URI reference that identifies the specific occurrence of the problem.","type":"string"}},"type":"object","$$ref":"#/components/schemas/Error"}}},"description":"Not found"},"429":{"content":{"application/problem+json":{"schema":{"properties":{"type":{"description":"A URI reference that identifies the problem type. When this member is not present, its value is assumed to be \"about:blank\".","type":"string"},"title":{"description":"A short, human-readable summary of the problem type.","type":"string"},"status":{"description":"The HTTP status code generated by the origin server for this occurrence of the problem.","type":"integer"},"detail":{"description":"A human-readable explanation specific to this occurrence of the problem.","type":"string"},"instance":{"description":"A URI reference that identifies the specific occurrence of the problem.","type":"string"}},"type":"object","$$ref":"#/components/schemas/Error"}}},"description":"Exhausted rate limit for the organization"},"500":{"content":{"application/problem+json":{"example":{"type":"about:blank","title":"Internal server error","status":500,"detail":"Optional detail about the internal error message.","instance":"/v7"},"schema":{"properties":{"type":{"description":"A URI reference that identifies the problem type. When this member is not present, its value is assumed to be \"about:blank\".","type":"string"},"title":{"description":"A short, human-readable summary of the problem type.","type":"string"},"status":{"description":"The HTTP status code generated by the origin server for this occurrence of the problem.","type":"integer"},"detail":{"description":"A human-readable explanation specific to this occurrence of the problem.","type":"string"},"instance":{"description":"A URI reference that identifies the specific occurrence of the problem.","type":"string"}},"type":"object","$$ref":"#/components/schemas/Error"}}},"description":"Internal server error"}},"summary":"Get usage information for the last month","tags":["Usage"],"__originalOperationId":"getUsage","security":[{"BearerAuth":[]}],"method":"get","path":"/usage"}}