openapi: 3.2.0
info:
  version: 7.0.100
  title: Usage Quotas API
  description: "These 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    * The `agentId` field in enterprise agent unit responses may be omitted when not available.\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"
  x-provenance:
    method: harvested
    authored_by: Cisco ThousandEyes
    harvested_by: API Evangelist
    harvested_on: '2026-08-19'
    first_party: true
    provider_published: true
    source_host: pubhub.devnetcloud.com
    note: 27 OpenAPI 3.0 documents (26 per-area plus a unified 326-operation document) served anonymously from Cisco's DevNet CDN. api.thousandeyes.com itself 401s every path, so the contract is public while the API host is gated.
  x-evidence:
  - type: source
    url: https://pubhub.devnetcloud.com/media/000-v7-apis/docs/reference/
  - type: source
    url: https://developer.cisco.com/docs/thousandeyes/
servers:
- description: ThousandEyes API production URL
  url: https://api.thousandeyes.com/v7
security:
- BearerAuth: []
tags:
- name: Quotas
  description: Quota CRUD Operation
paths:
  /quotas:
    get:
      tags:
      - Quotas
      summary: Get organization and account group usage quota
      operationId: getQuotas
      description: This operation retrieves usage quotas for both organization and account groups. To use this endpoint, you need the `Edit organization and account group quotas` permission, which is a management-level permission. If a user has quota update permission in multiple organizations, the API returns data from all such organizations.
      responses:
        '200':
          description: OK
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/Quotas'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
        '429':
          $ref: '#/components/responses/429'
        '500':
          $ref: '#/components/responses/500'
  /quotas/assign:
    post:
      tags:
      - Quotas
      summary: Create or update organizations quotas
      operationId: assignOrganizationsQuotas
      description: This operation recieves a list of organization quotas to create or update. If there's no specific `orgId` defined for a quota, it defaults to using the authenticated organization. To use this endpoint, you need the `Edit organization and account group quotas` permission, which is a management-level permission. This operation follows cumulative behavior––This means that the quotas are assigned to the specified organizations, and any previous assignments remain unchanged; no unassignments occur.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/QuotasAssignRequest'
      responses:
        '200':
          description: OK
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/QuotasAssignResponse'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
        '429':
          $ref: '#/components/responses/429'
        '500':
          $ref: '#/components/responses/500'
  /quotas/unassign:
    post:
      tags:
      - Quotas
      summary: Remove organization quotas
      operationId: unassignOrganizationsQuotas
      description: This operation recieves a list of organization IDs to remove their current quota. To use this endpoint, you need the `Edit organization and account group quotas` permission, which is a management-level permission.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/QuotasUnassign'
      responses:
        '204':
          $ref: '#/components/responses/204'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
        '429':
          $ref: '#/components/responses/429'
        '500':
          $ref: '#/components/responses/500'
  /quotas/account-groups/assign:
    post:
      tags:
      - Quotas
      summary: Create or update accout group quotas
      operationId: assignOrganizationsAccountGroupsQuotas
      description: This operation assigns quota values to multiple account groups across multiple organizations. To use this endpoint, you need the `Edit organization and account group quotas` permission, which is a management-level permission. This operation follows a cumulative behavior––This means that the quotas are assigned to the designated account groups, and any previous assignments remain in place without any unassignment occurring.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OrganizationsQuotasAssign'
      responses:
        '200':
          description: OK
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/OrganizationsQuotasAssign'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
        '429':
          $ref: '#/components/responses/429'
        '500':
          $ref: '#/components/responses/500'
  /quotas/account-groups/unassign:
    post:
      tags:
      - Quotas
      summary: Remove account group quotas from organizations
      operationId: unassignOrganizationsAccountGroupsQuotas
      description: This operation removes quotas from multiple account groups across multiple organizations. To use this endpoint, you need the `Edit organization and account group quotas` permission, which is a management-level permission.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OrganizationsQuotasUnassign'
      responses:
        '204':
          $ref: '#/components/responses/204'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
        '429':
          $ref: '#/components/responses/429'
        '500':
          $ref: '#/components/responses/500'
components:
  schemas:
    ValidationError:
      type: object
      allOf:
      - $ref: '#/components/schemas/Error'
      - type: object
        properties:
          errors:
            type:
            - array
            - 'null'
            description: (Optional) When multiple errors occur, the details for each error are listed.
            items:
              $ref: '#/components/schemas/ValidationErrorItem'
    AccountGroupIds:
      type: array
      description: List of account group IDs.
      items:
        type: string
      example:
      - '1234'
      - '12345'
    QuotasAssignResponse:
      type: object
      properties:
        organizations:
          type: array
          items:
            $ref: '#/components/schemas/OrganizationQuota'
          example:
          - orgId: '1234'
            value: 12000
          - orgId: '12345'
            value: 10000
    AccountGroupQuota:
      type: object
      properties:
        value:
          type: integer
          format: int64
          description: Value of the quota for the given Account Group.
          example: 12000
        aid:
          type: string
          description: Unique ID of the account group.
          example: '1234'
    ValidationErrorItem:
      type: object
      properties:
        code:
          type: string
          description: (Optional) A unique error type/code that can be referenced in the documentation for further details.
        field:
          type: string
          description: Identifies the field that triggered this particular error.
        message:
          type: string
          description: A short, human-readable summary of the error.
    OrganizationsQuotasUnassign:
      type: object
      properties:
        organizations:
          type: array
          items:
            $ref: '#/components/schemas/OrganizationQuotaUnassignment'
    OrganizationsQuotasAssign:
      type: object
      properties:
        organizations:
          type: array
          items:
            $ref: '#/components/schemas/OrganizationQuotaAssignment'
    OrganizationQuota:
      type: object
      required:
      - value
      properties:
        value:
          type: integer
          format: int64
          description: Value of the quota for the given Organization.
          example: 22500
        orgId:
          type: string
          description: Unique ID of the organization.
          example: '10'
    OrganizationQuotaUnassignment:
      type: object
      properties:
        orgId:
          type: string
          description: Unique identifier of the organization.
          example: '1234'
        accountGroups:
          $ref: '#/components/schemas/AccountGroupIds'
    QuotasAssignRequest:
      type: object
      properties:
        organizations:
          type: array
          items:
            $ref: '#/components/schemas/OrganizationQuota'
          example:
          - value: 12000
          - orgId: '1234'
            value: 10000
    UnauthorizedError:
      type: object
      properties:
        error:
          type: string
          example: invalid_token
        error_description:
          type: string
          example: Invalid access token
    Link:
      type: object
      description: A hyperlink from the containing resource to a URI.
      required:
      - href
      properties:
        href:
          type: string
          description: Its value is either a URI [RFC3986] or a URI template [RFC6570].
          example: https://api.thousandeyes.com/v7/link/to/resource/id
        templated:
          type: boolean
          description: Should be true when the link object's "href" property is a URI template.
        type:
          type: string
          description: Used as a hint to indicate the media type expected when dereferencing the target resource.
        deprecation:
          type: string
          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.
        name:
          type: string
          description: Its value may be used as a secondary key for selecting link objects that share the same relation type.
        profile:
          type: string
          description: A URI that hints about the profile of the target resource.
        title:
          type: string
          description: Intended for labelling the link with a human-readable identifier
        hreflang:
          type: string
          description: Indicates the language of the target resource
    Error:
      type: object
      properties:
        type:
          type: string
          description: A URI reference that identifies the problem type. When this member is not present, its value is assumed to be "about:blank".
        title:
          type: string
          description: A short, human-readable summary of the problem type.
        status:
          type: integer
          description: The HTTP status code generated by the origin server for this occurrence of the problem.
        detail:
          type: string
          description: A human-readable explanation specific to this occurrence of the problem.
        instance:
          type: string
          description: A URI reference that identifies the specific occurrence of the problem.
    Quotas:
      type: object
      properties:
        quotas:
          type: array
          items:
            $ref: '#/components/schemas/Quota'
        _links:
          $ref: '#/components/schemas/SelfLinks'
    QuotasUnassign:
      type: object
      properties:
        organizations:
          type: array
          items:
            type: string
          example:
          - '1234'
          - '12345'
    OrganizationQuotaAssignment:
      type: object
      properties:
        orgId:
          type: string
          description: Unique identifier of the organization.
          example: '1234'
        accountGroups:
          type: array
          description: List of account groups quotas.
          items:
            $ref: '#/components/schemas/AccountGroupQuota'
    Quota:
      type: object
      properties:
        organizationQuota:
          $ref: '#/components/schemas/OrganizationQuota'
        accountGroupQuotas:
          type: array
          items:
            $ref: '#/components/schemas/AccountGroupQuota'
          example:
          - value: 12000
            aid: '1234'
          - value: 10000
            aid: '12345'
    SelfLinks:
      type: object
      description: A links object containing the self link.
      readOnly: true
      properties:
        self:
          $ref: '#/components/schemas/Link'
  responses:
    '429':
      description: Exhausted rate limit for the organization
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Error'
    '404':
      description: Not found
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Error'
          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
    '500':
      description: Internal server error
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            type: about:blank
            title: Internal server error
            status: 500
            detail: Optional detail about the internal error message.
            instance: /v7
    '400':
      description: Bad Request
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/ValidationError'
          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
    '403':
      description: Insufficient permissions to query endpoint
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Error'
    '401':
      description: Unauthorized
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/UnauthorizedError'
    '204':
      description: No content
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: Bearer authentication token
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