openapi: 3.1.0
info:
  title: Palo Alto Networks AIOps for NGFW BPA 5G Deregistered Trend Statistics API
  description: AIOps for NGFW Best Practice Assessment (BPA) API. Provides programmatic access to submit BPA requests for Palo Alto Networks next-generation firewalls, check request processing status, and retrieve completed assessment reports. BPA reports analyze firewall configurations against Palo Alto Networks best practices and security benchmarks, identifying gaps and providing remediation guidance to improve security posture. Part of the Strata Cloud Manager platform.
  version: '1.0'
  contact:
    name: Palo Alto Networks Developer Support
    url: https://pan.dev/
  license:
    name: Proprietary
    url: https://www.paloaltonetworks.com/legal
servers:
- url: https://api.stratacloud.paloaltonetworks.com/aiops/bpa/v1
  description: AIOps for NGFW BPA API production server.
security:
- oauth2Bearer: []
tags:
- name: Statistics
  description: Network access and DNS query statistics.
paths:
  /stats/network:
    get:
      operationId: getNetworkStats
      summary: Palo Alto Networks Get Network Access Statistics
      description: Returns DNS query and network access statistics for a customer's environment within a specified time range. Supports filtering by domain to return per-domain statistics. Useful for monitoring DNS query volumes, identifying anomalous lookup patterns, and generating compliance reports on DNS Security policy enforcement activity.
      tags:
      - Statistics
      parameters:
      - name: customerid
        in: query
        required: true
        description: Customer ID for which to return network statistics.
        schema:
          type: string
        example: '509945'
      - name: domain
        in: query
        required: false
        description: Filter statistics to a specific domain. When omitted, aggregate statistics for all domains are returned.
        schema:
          type: string
        example: api.test-corp.net
      - name: stime
        in: query
        required: true
        description: Start time for the statistics period in ISO 8601 format or Unix epoch seconds.
        schema:
          type: string
        example: example-stime
      - name: etime
        in: query
        required: true
        description: End time for the statistics period in ISO 8601 format or Unix epoch seconds.
        schema:
          type: string
        example: example-etime
      responses:
        '200':
          description: Network access statistics returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NetworkStats'
              examples:
                GetNetworkStats200Example:
                  summary: Default getNetworkStats 200 response
                  x-microcks-default: true
                  value:
                    customerid: '251301'
                    period:
                      start: example-start
                      end: example-end
                    total_queries: 301
                    blocked_queries: 169
                    allowed_queries: 331
                    sinkholed_queries: 260
                    top_queried_domains:
                    - domain: vpn.acme-systems.org
                      query_count: 57
                      dns_security_category: advanced
                    category_breakdown:
                    - category: custom
                      count: 310
                      percentage: 40.54
        '400':
          description: Invalid query parameters or time range.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                GetNetworkStats400Example:
                  summary: Default getNetworkStats 400 response
                  x-microcks-default: true
                  value:
                    error: example-error
                    message: Security monitoring rule detected on threat network suspicious.
                    request_id: 583d1742-dcda-461e-a765-4a0c8e530ab5
        '401':
          description: Invalid or missing X-DNS-API-APIKEY header.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                GetNetworkStats401Example:
                  summary: Default getNetworkStats 401 response
                  x-microcks-default: true
                  value:
                    error: example-error
                    message: Security monitoring rule detected on threat network suspicious.
                    request_id: 583d1742-dcda-461e-a765-4a0c8e530ab5
        '403':
          description: DNS Security subscription not active.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                GetNetworkStats403Example:
                  summary: Default getNetworkStats 403 response
                  x-microcks-default: true
                  value:
                    error: example-error
                    message: Security monitoring rule detected on threat network suspicious.
                    request_id: 583d1742-dcda-461e-a765-4a0c8e530ab5
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                GetNetworkStats500Example:
                  summary: Default getNetworkStats 500 response
                  x-microcks-default: true
                  value:
                    error: example-error
                    message: Security monitoring rule detected on threat network suspicious.
                    request_id: 583d1742-dcda-461e-a765-4a0c8e530ab5
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  schemas:
    NetworkStats:
      type: object
      properties:
        customerid:
          type: string
          description: Customer ID for which statistics are returned.
          example: '251301'
        period:
          type: object
          properties:
            start:
              type: string
              description: Start of the statistics period.
              example: example-start
            end:
              type: string
              description: End of the statistics period.
              example: example-end
          example:
            start: example-start
            end: example-end
        total_queries:
          type: integer
          description: Total DNS queries processed during the period.
          example: 301
        blocked_queries:
          type: integer
          description: DNS queries blocked by DNS Security policy.
          example: 169
        allowed_queries:
          type: integer
          description: DNS queries allowed by DNS Security policy.
          example: 331
        sinkholed_queries:
          type: integer
          description: DNS queries redirected to sinkhole.
          example: 260
        top_queried_domains:
          type: array
          description: Most frequently queried domains during the period.
          items:
            type: object
            properties:
              domain:
                type: string
                example: api.example.com
              query_count:
                type: integer
                example: 628
              dns_security_category:
                type: string
                example: standard
          example:
          - domain: vpn.acme-systems.org
            query_count: 57
            dns_security_category: advanced
        category_breakdown:
          type: array
          description: Query counts grouped by DNS Security category.
          items:
            type: object
            properties:
              category:
                type: string
                example: custom
              count:
                type: integer
                example: 698
              percentage:
                type: number
                format: float
                example: 66.42
          example:
          - category: custom
            count: 310
            percentage: 40.54
    ErrorResponse:
      type: object
      properties:
        error:
          type: string
          description: Error code identifying the error type.
          example: example-error
        message:
          type: string
          description: Human-readable description of the error.
          example: Security monitoring rule detected on threat network suspicious.
        request_id:
          type: string
          description: Request identifier for support correlation.
          example: 583d1742-dcda-461e-a765-4a0c8e530ab5
  securitySchemes:
    oauth2Bearer:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: OAuth 2.0 Bearer token for SASE platform authentication. Obtain using the client_credentials grant with your SASE service account client ID and client secret.