{"type":"api","title":"Get cloud and enterprise agents units usage","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 the cloud and enterprise agents usage for all the tests for a specific time period, or the curent billing cycle if no time period is specified.\nIn the `/v7/usage` API, an enterprise agent's usage is reported in the account group where the agent was created (i.e Primary Account Group). However in this API, the agent's usage is distributed among all the account groups where the tests are running on the particular agent. This API is also only available to customers on usage based pricing model.","operationId":"getTestsUnitsUsage","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":"Use with the `endDate` parameter. Include the complete time (hours, minutes, and seconds) in UTC time zone, following the ISO 8601 date-time format. See the example for reference. Please note that this parameter can't be used with `window`.","in":"query","name":"startDate","schema":{"example":"2022-07-17T22:00:54Z","format":"date-time","type":"string"}},{"description":"Defaults to current time the request is made. Use with the `startDate` parameter. Include the complete time (hours, minutes, and seconds) in UTC time zone, following the ISO 8601 date-time format. See the example for reference. Please note that this parameter can't be used with `window`.","in":"query","name":"endDate","schema":{"example":"2022-07-18T22:00:54Z","format":"date-time","type":"string"}},{"description":"(Optional) Opaque cursor used for pagination. Clients should use `next` value from `_links` instead of this parameter.","in":"query","name":"cursor","schema":{"type":"string","example":null}}],"responses":{"200":{"content":{"application/hal+json":{"schema":{"properties":{"breakdowns":{"example":[{"testId":"1158","testName":"https://app.thousandeyes.com","testType":"Web-Page Load","enterpriseUnitsUsed":14050,"enterpriseUnitsProjected":340674,"cloudUnitsUsed":10000,"cloudUnitsProjected":12000,"aid":"1234","accountGroupName":"Support"},{"testId":"1221","testName":"https://app.thousandeyes.com","testType":"Web - HTTP Server","enterpriseUnitsUsed":194051,"enterpriseUnitsProjected":30622,"cloudUnitsUsed":12000,"cloudUnitsProjected":13000,"aid":"1234","accountGroupName":"Support"}],"items":{"properties":{"aid":{"description":"Unique ID of the account group owning the test that is generating units","example":"1234","type":"string"},"accountGroupName":{"description":"Name of the account group which owns the test that is generating the units","example":"Account A","type":"string"},"enterpriseUnitsUsed":{"description":"Units generated by the by the enterprise agents running the test","type":"integer"},"enterpriseUnitsProjected":{"description":"Enterprise Units projected in the current usage period, based on units consumed to date and configuration of the test","type":"integer"},"cloudUnitsUsed":{"description":"Units generated by the by the cloud agents running the test","type":"integer"},"cloudUnitsProjected":{"description":"Cloud Units projected in the current usage period, based on units consumed to date and configuration of the test","type":"integer"},"testId":{"description":"Unique ID of the test generating usage","type":"string"},"testName":{"description":"Name of the test generating usage","type":"string"},"testType":{"description":"Type of test generating usage. Note that this is a friendly testType entry (so it shouldn’t be parsed to discover the correct operation to query for configuration details).","type":"string"},"isInstantTest":{"description":"Indicates whether the test is scheduled or instant","type":"boolean"}},"type":"object","$$ref":"#/components/schemas/UnitsByTests"},"type":"array","x-paginated-items":true},"_links":{"description":"A links object containing pagination related link(s).","properties":{"previous":{"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"},"next":{"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"},"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"}},"type":"object","$$ref":"#/components/schemas/PaginationLinks"}},"type":"object","$$ref":"#/components/schemas/TestsUsage"}}},"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 cloud and enterprise agents units usage","tags":["Usage"],"__originalOperationId":"getTestsUnitsUsage","security":[{"BearerAuth":[]}],"method":"get","path":"/usage/units/tests"}}