openapi: 3.0.0
info:
  title: Cisco Umbrella API Usage Reports
  version: 2.0.0
  description: Get the Umbrella API usage reports for an organization.
  contact:
    name: Cloud Security Developer Community
  x-provenance:
    method: harvested
    authored_by: Cisco Umbrella
    harvested_by: API Evangelist
    harvested_on: '2026-08-19'
    first_party: true
    provider_published: true
    source_host: pubhub.devnetcloud.com
    note: 26 first-party OpenAPI 3.0 documents (256 operations) listed by Cisco's own docs-nav config and fetched anonymously.
      Byte-identity reconfirmed 2026-08-19 by SHA-256 against the live source.
  x-evidence:
  - type: source
    url: https://pubhub.devnetcloud.com/media/cloud-security-apis-in-eft/docs/umbrella-config.json
  - type: source
    url: https://developer.cisco.com/docs/cloud-security/
servers:
- url: https://api.umbrella.com/{basePath}
  variables:
    basePath:
      default: reports/v2
tags:
- name: API Usage Report
  description: API Usage reports
- name: Umbrella
security:
- oauthFlow: []
paths:
  /apiUsage/requests:
    get:
      operationId: getAPIUsageRequests
      summary: Get Requests
      description: 'Get the information about the API requests for the organization within a specific time period, including

        the total number of API requests for the type of client program.'
      tags:
      - API Usage Report
      - Umbrella
      security:
      - oauthFlow:
        - reports.apiusage:read
      parameters:
      - $ref: '#/components/parameters/from'
      - $ref: '#/components/parameters/to'
      - $ref: '#/components/parameters/apiKeys'
      - $ref: '#/components/parameters/paths'
      - $ref: '#/components/parameters/verbs'
      - $ref: '#/components/parameters/statusCodes'
      - $ref: '#/components/parameters/userAgents'
      responses:
        '200':
          description: OK
          headers:
            Content-Type:
              $ref: '#/components/headers/Content-Type'
            Date:
              $ref: '#/components/headers/Date'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/requests'
              example:
                from: '2023-12-03'
                to: '2023-12-04'
                count: 100
                items:
                - userAgent: python-requests/2.20.0
                  count: 2529
                  requests:
                  - path: auth/v2/token
                    verb: POST
                    count: 928
                  - path: /reports/v2/activity/proxy
                    verb: GET
                    count: 801
                  - path: /reports.us/v2/activity/proxy
                    verb: GET
                    count: 800
        '400':
          $ref: '#/components/responses/400Error'
        '401':
          $ref: '#/components/responses/401Error'
        '403':
          $ref: '#/components/responses/403Error'
        '404':
          $ref: '#/components/responses/404Error'
        '500':
          $ref: '#/components/responses/500Error'
  /apiUsage/responses:
    get:
      operationId: getAPIUsageResponses
      summary: Get Responses
      description: 'Get the information about the API responses for the organization within a specific time period, including

        the total number of API responses and the HTTP status codes.'
      tags:
      - API Usage Report
      - Umbrella
      security:
      - oauthFlow:
        - reports.apiusage:read
      parameters:
      - $ref: '#/components/parameters/from'
      - $ref: '#/components/parameters/to'
      - $ref: '#/components/parameters/apiKeys'
      - $ref: '#/components/parameters/paths'
      - $ref: '#/components/parameters/verbs'
      - $ref: '#/components/parameters/statusCodes'
      - $ref: '#/components/parameters/userAgents'
      responses:
        '200':
          description: OK
          headers:
            Content-Type:
              $ref: '#/components/headers/Content-Type'
            Date:
              $ref: '#/components/headers/Date'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/responses'
              example:
                from: '2023-12-03'
                to: '2023-12-04'
                count: 566
                items:
                - statusCode: '401'
                  count: 566
                  requests:
                  - path: /deployments/v2/networks
                    verb: GET
                    count: 546
                  - path: /deployments/v2/virtualappliances
                    verb: POST
                    count: 16
                  - path: /deployments/v2/internaldomains
                    verb: GET
                    count: 4
        '400':
          $ref: '#/components/responses/400Error'
        '401':
          $ref: '#/components/responses/401Error'
        '403':
          $ref: '#/components/responses/403Error'
        '404':
          $ref: '#/components/responses/404Error'
        '500':
          $ref: '#/components/responses/500Error'
  /apiUsage/keys:
    get:
      operationId: getAPIUsageKeys
      summary: Get Keys
      description: Get the API key usage information, including the total number of API requests within a specific time period.
      tags:
      - API Usage Report
      - Umbrella
      security:
      - oauthFlow:
        - reports.apiusage:read
      parameters:
      - $ref: '#/components/parameters/from'
      - $ref: '#/components/parameters/to'
      - $ref: '#/components/parameters/apiKeys'
      - $ref: '#/components/parameters/paths'
      - $ref: '#/components/parameters/verbs'
      - $ref: '#/components/parameters/statusCodes'
      - $ref: '#/components/parameters/userAgents'
      responses:
        '200':
          description: OK
          headers:
            Content-Type:
              $ref: '#/components/headers/Content-Type'
            Date:
              $ref: '#/components/headers/Date'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/keys'
              example:
                from: '2023-12-03'
                to: '2023-12-04'
                count: 566
                items:
                - keyName: Deployments API key
                  keyId: 124afg
                  count: 5000
                  requests:
                  - path: /deployments/v2/roamingcomputers
                    verb: GET
                    count: 4
                  - path: /deployments/v2/networks
                    verb: GET
                    count: 10
        '400':
          $ref: '#/components/responses/400Error'
        '401':
          $ref: '#/components/responses/401Error'
        '403':
          $ref: '#/components/responses/403Error'
        '404':
          $ref: '#/components/responses/404Error'
        '500':
          $ref: '#/components/responses/500Error'
  /apiUsage/summary:
    get:
      operationId: getAPIUsageSummary
      summary: Get Summary
      description: Get the total number API requests, and the counts of the successful and failed API requests within a specific
        time period.
      tags:
      - API Usage Report
      - Umbrella
      security:
      - oauthFlow:
        - reports.apiusage:read
      parameters:
      - $ref: '#/components/parameters/from'
      - $ref: '#/components/parameters/to'
      - $ref: '#/components/parameters/apiKeys'
      - $ref: '#/components/parameters/paths'
      - $ref: '#/components/parameters/verbs'
      - $ref: '#/components/parameters/statusCodes'
      - $ref: '#/components/parameters/userAgents'
      responses:
        '200':
          description: OK
          headers:
            Content-Type:
              $ref: '#/components/headers/Content-Type'
            Date:
              $ref: '#/components/headers/Date'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/summary'
              example:
                data:
                  successfulRequests: 20
                  failedRequests: 5
                  total: 25
        '400':
          $ref: '#/components/responses/400Error'
        '401':
          $ref: '#/components/responses/401Error'
        '403':
          $ref: '#/components/responses/403Error'
        '404':
          $ref: '#/components/responses/404Error'
        '500':
          $ref: '#/components/responses/500Error'
components:
  headers:
    Content-Type:
      schema:
        type: string
      description: The MIME content type of the response body.
      example: application/json
    Date:
      schema:
        type: string
        pattern: ^[0-90-90-90-9-0-90-9-0-90-9T0-90-9:0-90-9:0-90-9Z]+$
      description: The timestamp of the response.
      example: '2023-03-14T18:34:25Z'
  parameters:
    from:
      name: from
      in: query
      description: 'The date and time specified in the RFC-3339 format, for example: 2023-10-01.

        Filter the collection for data that appears after this time.'
      required: true
      schema:
        type: string
      example: '2023-10-01'
    to:
      name: to
      in: query
      description: 'The date and time specified in the RFC-3339 format, for example: 2023-10-01.

        Filter the collection for data that appears before this time.'
      required: true
      schema:
        type: string
      example: '2023-10-01'
    apiKeys:
      name: apiKeys
      in: query
      description: Sort the collection using a list of comma-separated API key IDs.
      required: false
      schema:
        type: string
      example: 123abfs77632
    verbs:
      name: verbs
      in: query
      description: 'Sort the collection using a list of comma-separated HTTP verbs.

        The HTTP verb strings are case sensitive.'
      required: false
      schema:
        type: string
      example: GET,POST,PUT
    paths:
      name: paths
      in: query
      description: Sort the collection using a list of comma-separated API resource paths.
      required: false
      schema:
        type: string
      example: policies/v2/destinationlists/1234556,policies/v2/destinationlists
    statusCodes:
      name: statusCodes
      in: query
      description: Sort the collection using a list of comma-separated HTTP status codes.
      required: false
      schema:
        type: string
      example: 200,204,429
    userAgents:
      name: userAgents
      in: query
      description: Sort the collection using a list of comma-separated labels that describe the HTTP client programs.
      required: false
      schema:
        type: string
      example: python-requests/2.20.0,Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/116.0.0.0
        Safari/537.36
  schemas:
    count:
      type: integer
      format: int32
      description: The total number of API requests.
      example: 450
    from:
      type: string
      description: The date and time where to start reading in the collection.
      example: '2023-12-03'
    to:
      type: string
      description: The date and time where to stop reading in the collection.
      example: '2023-12-05'
    message:
      type: string
      description: The description of the error.
      example: Internal Server Error
    code:
      type: integer
      description: The status code of the error.
      example: 500
    response:
      type: object
      properties:
        meta:
          type: object
          example: {}
        data:
          type: object
          properties:
            errors:
              type: string
              description: The information about the error condition.
              example: missing required parameters
            requiredParameters:
              type: array
              description: The list of query parameters that you must include in the API request.
              items:
                type: string
                description: The name of the query parameters on the API endpoint.
                example: to
              example:
              - from
              - to
      example:
        meta: {}
        data:
          errors: missing required parameters
        requiredParameters:
        - to
        - from
    requestsInformation:
      type: array
      description: The information about the API requests.
      items:
        type: object
        required:
        - userAgent
        - count
        - requests
        properties:
          userAgent:
            type: string
            description: The name of the client program.
            example: python-requests/2.20.0
          count:
            $ref: '#/components/schemas/count'
          requests:
            $ref: '#/components/schemas/requestDetailsList'
      example:
      - userAgent: python-requests/2.20.0
        count: 2529
        requests:
        - path: auth/v2/token
          verb: POST
          count: 928
        - path: /reports/v2/activity/proxy
          verb: GET
          count: 801
        - path: /reports.us/v2/activity/proxy
          verb: GET
          count: 800
      - userAgent: Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/116.0.0.0 Safari/537.36
        count: 13
        requests:
        - path: /policies/v2/destinationlists
          verb: GET
          count: 13
    requestDetailsList:
      type: array
      description: The list of API request information.
      items:
        type: object
        required:
        - path
        - verb
        - count
        properties:
          path:
            type: string
            description: The path of the API endpoint.
            example: /reports/v2/activity/proxy
          verb:
            type: string
            description: The name of the API operation.
            example: GET
          count:
            type: integer
            description: The number of requests to the API endpoint.
            format: int64
            example: 928
        example:
          path: /auth/v2/token
          verb: POST
          count: 928
      example:
      - path: /auth/v2/token
        verb: POST
        count: 928
    responsesInformation:
      type: array
      description: The list of information about API responses for the API requests.
      items:
        type: object
        required:
        - statusCode
        - count
        - requests
        properties:
          statusCode:
            type: string
            description: The HTTP response status code.
            example: '204'
          count:
            $ref: '#/components/schemas/count'
          requests:
            $ref: '#/components/schemas/requestDetailsList'
      example:
      - statusCode: '302'
        count: 2667
        requests:
        - path: /reports/v2/activity/proxy
          verb: GET
          count: 2667
      - statusCode: '200'
        count: 6000
        requests:
        - path: /auth/v2/token
          verb: POST
          count: 4204
        - path: /reports.us/v2/activity/proxy
          verb: GET
          count: 2661
      - statusCode: '401'
        count: 566
        requests:
        - path: /policies/v2/destinationlists
          verb: GET
          count: 546
        - path: /policies/v2/destinationlists
          verb: POST
          count: 16
        - path: /policies/v2/destinationlists/{destinationListId}
          verb: GET
          count: 4
    requests:
      type: object
      description: The information about the API requests.
      required:
      - from
      - to
      - count
      - items
      properties:
        from:
          $ref: '#/components/schemas/from'
        to:
          $ref: '#/components/schemas/to'
        count:
          $ref: '#/components/schemas/count'
        items:
          $ref: '#/components/schemas/requestsInformation'
      example:
        from: '2023-12-03'
        to: '2023-12-04'
        count: 100
        items:
        - userAgent: python-requests/2.20.0
          count: 2529
          requests:
          - path: auth/v2/token
            verb: POST
            count: 928
          - path: /reports/v2/activity/proxy
            verb: GET
            count: 801
          - path: /reports.us/v2/activity/proxy
            verb: GET
            count: 800
    responses:
      type: object
      description: The information about the API responses.
      required:
      - from
      - to
      - count
      - items
      properties:
        from:
          $ref: '#/components/schemas/from'
        to:
          $ref: '#/components/schemas/to'
        count:
          $ref: '#/components/schemas/count'
        items:
          $ref: '#/components/schemas/responsesInformation'
      example:
        from: '2023-12-03'
        to: '2023-12-04'
        count: 100
        items:
        - statusCode: '401'
          count: 566
          requests:
          - path: /reports/v2/activity/proxy
            verb: GET
            count: 546
          - path: /deployments/v2/networks
            verb: POST
            count: 16
          - path: /deployments/v2/roamingcomputers
            verb: GET
            count: 4
    keysInformation:
      type: array
      description: The information about the API key usage.
      items:
        type: object
        required:
        - count
        - requests
        - keyName
        - keyId
        properties:
          keyName:
            type: string
            description: The name of the API key.
            example: Deployments API key
          keyId:
            type: string
            description: The ID of the API key.
            example: 12345345345a
          count:
            $ref: '#/components/schemas/count'
          requests:
            $ref: '#/components/schemas/requestDetailsList'
      example:
      - keyName: Reports and Policies API key
        keyId: ajsdk12455555
        count: 400
        requests:
        - path: /reports/v2/activity/proxy
          verb: GET
          count: 546
        - path: /policies/v2/destinationlists
          verb: POST
          count: 16
        - path: /policies/v2/destinationlists
          verb: GET
          count: 4
    keys:
      type: object
      description: The information about the API key usage.
      required:
      - from
      - to
      - count
      - items
      properties:
        from:
          $ref: '#/components/schemas/from'
        to:
          $ref: '#/components/schemas/to'
        count:
          $ref: '#/components/schemas/count'
        items:
          $ref: '#/components/schemas/keysInformation'
      example:
        from: '2023-12-03'
        to: '2023-12-04'
        count: 100
        items:
        - keyName: Reports and Policies API key
          keyId: ajsdk12455555
          count: 400
          requests:
          - path: /reports/v2/activity/proxy
            verb: GET
            count: 546
          - path: /policies/v2/destinationlists
            verb: POST
            count: 16
          - path: /policies/v2/destinationlists
            verb: GET
            count: 4
    summary:
      type: object
      description: The summary of the API usage.
      required:
      - data
      properties:
        data:
          type: object
          description: The total number of requsts and the counts of the failed and successful requests.
          required:
          - successfulRequests
          - failedRequests
          - total
          properties:
            successfulRequests:
              type: integer
              description: The number of successful API requests.
              example: 20
            failedRequests:
              type: integer
              description: The number of failed API requests.
              example: 5
            total:
              type: integer
              description: The total number of API requests.
              example: 25
      example:
        data:
          successfulRequests: 20
          failedRequests: 5
          total: 25
  securitySchemes:
    oauthFlow:
      type: oauth2
      description: Client credential flow
      flows:
        clientCredentials:
          tokenUrl: https://api.umbrella.com/auth/v2/token
          scopes:
            reports.apiusage:read: Read the API Usage reports
  responses:
    400Error:
      description: Bad Request
      headers:
        Content-Type:
          $ref: '#/components/headers/Content-Type'
        Date:
          $ref: '#/components/headers/Date'
      content:
        application/json:
          schema:
            type: object
            properties:
              message:
                $ref: '#/components/schemas/message'
              code:
                $ref: '#/components/schemas/code'
            example:
              message: Bad Request
              code: 400
    400ErrorMissingParams:
      description: Bad Request
      headers:
        Content-Type:
          $ref: '#/components/headers/Content-Type'
        Date:
          $ref: '#/components/headers/Date'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/response'
          example:
            meta: {}
            data:
              errors: Missing required parameters
              requiredParameters:
              - from
              - to
    401Error:
      description: Unauthorized
      content:
        application/json:
          schema:
            type: object
            properties:
              message:
                $ref: '#/components/schemas/message'
              code:
                $ref: '#/components/schemas/code'
            example:
              message: Unauthorized
              code: 401
      headers:
        Content-Type:
          $ref: '#/components/headers/Content-Type'
        Date:
          $ref: '#/components/headers/Date'
    403Error:
      description: Forbidden
      content:
        application/json:
          schema:
            type: object
            properties:
              message:
                $ref: '#/components/schemas/message'
              code:
                $ref: '#/components/schemas/code'
            example:
              message: Forbidden
              code: 403
      headers:
        Content-Type:
          $ref: '#/components/headers/Content-Type'
        Date:
          $ref: '#/components/headers/Date'
    404Error:
      description: Not Found
      content:
        application/json:
          schema:
            type: object
            properties:
              message:
                $ref: '#/components/schemas/message'
              code:
                $ref: '#/components/schemas/code'
            example:
              message: Not Found
              code: 404
      headers:
        Content-Type:
          $ref: '#/components/headers/Content-Type'
        Date:
          $ref: '#/components/headers/Date'
    500Error:
      description: Internal Server Error
      content:
        application/json:
          schema:
            type: object
            properties:
              message:
                $ref: '#/components/schemas/message'
              code:
                $ref: '#/components/schemas/code'
            example:
              message: Internal Server Error
              code: 500
      headers:
        Content-Type:
          $ref: '#/components/headers/Content-Type'
        Date:
          $ref: '#/components/headers/Date'
x-provenance:
  method: harvested
  first_party: true
  harvested: '2026-08-19'
  source: https://pubhub.devnetcloud.com/media/cloud-security-apis-in-eft/docs/reference/reports/api-usage.yaml
  publisher: Cisco Systems, Inc. (Cisco DevNet Cloud Security docs)
x-evidence:
  fetched: '2026-08-19'
  url: https://pubhub.devnetcloud.com/media/cloud-security-apis-in-eft/docs/reference/reports/api-usage.yaml
  http_status: 200
  docs: https://developer.cisco.com/docs/cloud-security/