Palo Alto Networks Aggregation Queries API

openapi: 3.1.0
info:
  title: Palo Alto Networks AIOps for NGFW BPA 5G Deregistered Trend Aggregation Queries 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: Aggregation Queries
  description: Multi-tenant aggregated data queries.
paths:
  /agg/query/threat:
    post:
      operationId: queryThreatData
      summary: Palo Alto Networks Query Threat Data Aggregation
      description: Returns aggregated threat event data across one or more tenants within a Tenant Service Group hierarchy. Supports filtering by threat type, severity, source, and time range. Results can be grouped by dimensions such as tenant, threat category, or time bucket to support dashboard and reporting use cases.
      tags:
      - Aggregation Queries
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AggregationQuery'
            examples:
              QueryThreatDataRequestExample:
                summary: Default queryThreatData request
                x-microcks-default: true
                value:
                  tsg_id: '895182'
                  filter: {}
                  time_range:
                    start: '2025-05-13T00:30:44Z'
                    end: '2025-04-10T14:11:52Z'
                    last: example-last
                  count: 100
                  histogram:
                    field: example-field
                    interval: 1d
                  group_by:
                  - example-group_by_item
                  - example-group_by_item
                  sort:
                  - field: example-field
                    order: desc
      responses:
        '200':
          description: Threat data aggregation results returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AggregationResponse'
              examples:
                QueryThreatData200Example:
                  summary: Default queryThreatData 200 response
                  x-microcks-default: true
                  value:
                    total: 137
                    count: 29
                    time_range:
                      start: '2024-05-26T23:18:49Z'
                      end: '2024-01-19T02:12:28Z'
                    data:
                    - {}
                    - {}
                    histogram:
                    - timestamp: '2025-05-11T15:41:12Z'
                      count: 793
                      values: {}
                    - timestamp: '2024-09-14T11:54:08Z'
                      count: 283
                      values: {}
        '400':
          description: Invalid query request body.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                QueryThreatData400Example:
                  summary: Default queryThreatData 400 response
                  x-microcks-default: true
                  value:
                    error: example-error
                    message: Endpoint blocked traffic applied blocked on threat.
                    request_id: 34be728a-625b-4e23-9e3a-12d7366cb00d
        '401':
          description: Invalid or missing Bearer token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                QueryThreatData401Example:
                  summary: Default queryThreatData 401 response
                  x-microcks-default: true
                  value:
                    error: example-error
                    message: Endpoint blocked traffic applied blocked on threat.
                    request_id: 34be728a-625b-4e23-9e3a-12d7366cb00d
        '403':
          description: Insufficient permissions.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                QueryThreatData403Example:
                  summary: Default queryThreatData 403 response
                  x-microcks-default: true
                  value:
                    error: example-error
                    message: Endpoint blocked traffic applied blocked on threat.
                    request_id: 34be728a-625b-4e23-9e3a-12d7366cb00d
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                QueryThreatData500Example:
                  summary: Default queryThreatData 500 response
                  x-microcks-default: true
                  value:
                    error: example-error
                    message: Endpoint blocked traffic applied blocked on threat.
                    request_id: 34be728a-625b-4e23-9e3a-12d7366cb00d
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /agg/query/url:
    post:
      operationId: queryURLData
      summary: Palo Alto Networks Query URL Categorization Data
      description: Returns aggregated URL categorization and web activity data across tenants. Supports filtering by URL category, action, and user groups. Useful for generating web usage reports and identifying policy violations across managed tenants.
      tags:
      - Aggregation Queries
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AggregationQuery'
            examples:
              QueryUrldataRequestExample:
                summary: Default queryURLData request
                x-microcks-default: true
                value:
                  tsg_id: '895182'
                  filter: {}
                  time_range:
                    start: '2025-05-13T00:30:44Z'
                    end: '2025-04-10T14:11:52Z'
                    last: example-last
                  count: 100
                  histogram:
                    field: example-field
                    interval: 1d
                  group_by:
                  - example-group_by_item
                  - example-group_by_item
                  sort:
                  - field: example-field
                    order: desc
      responses:
        '200':
          description: URL categorization data returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AggregationResponse'
              examples:
                QueryUrldata200Example:
                  summary: Default queryURLData 200 response
                  x-microcks-default: true
                  value:
                    total: 137
                    count: 29
                    time_range:
                      start: '2024-05-26T23:18:49Z'
                      end: '2024-01-19T02:12:28Z'
                    data:
                    - {}
                    - {}
                    histogram:
                    - timestamp: '2025-05-11T15:41:12Z'
                      count: 793
                      values: {}
                    - timestamp: '2024-09-14T11:54:08Z'
                      count: 283
                      values: {}
        '400':
          description: Invalid query request body.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                QueryUrldata400Example:
                  summary: Default queryURLData 400 response
                  x-microcks-default: true
                  value:
                    error: example-error
                    message: Endpoint blocked traffic applied blocked on threat.
                    request_id: 34be728a-625b-4e23-9e3a-12d7366cb00d
        '401':
          description: Invalid or missing Bearer token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                QueryUrldata401Example:
                  summary: Default queryURLData 401 response
                  x-microcks-default: true
                  value:
                    error: example-error
                    message: Endpoint blocked traffic applied blocked on threat.
                    request_id: 34be728a-625b-4e23-9e3a-12d7366cb00d
        '403':
          description: Insufficient permissions.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                QueryUrldata403Example:
                  summary: Default queryURLData 403 response
                  x-microcks-default: true
                  value:
                    error: example-error
                    message: Endpoint blocked traffic applied blocked on threat.
                    request_id: 34be728a-625b-4e23-9e3a-12d7366cb00d
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                QueryUrldata500Example:
                  summary: Default queryURLData 500 response
                  x-microcks-default: true
                  value:
                    error: example-error
                    message: Endpoint blocked traffic applied blocked on threat.
                    request_id: 34be728a-625b-4e23-9e3a-12d7366cb00d
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /agg/query/application:
    post:
      operationId: queryApplicationData
      summary: Palo Alto Networks Query Application Usage Data
      description: Returns aggregated application usage data across tenants including session counts, bytes transferred, and user counts per application. Supports filtering by application name, category, and risk level.
      tags:
      - Aggregation Queries
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AggregationQuery'
            examples:
              QueryApplicationDataRequestExample:
                summary: Default queryApplicationData request
                x-microcks-default: true
                value:
                  tsg_id: '895182'
                  filter: {}
                  time_range:
                    start: '2025-05-13T00:30:44Z'
                    end: '2025-04-10T14:11:52Z'
                    last: example-last
                  count: 100
                  histogram:
                    field: example-field
                    interval: 1d
                  group_by:
                  - example-group_by_item
                  - example-group_by_item
                  sort:
                  - field: example-field
                    order: desc
      responses:
        '200':
          description: Application usage data returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AggregationResponse'
              examples:
                QueryApplicationData200Example:
                  summary: Default queryApplicationData 200 response
                  x-microcks-default: true
                  value:
                    total: 137
                    count: 29
                    time_range:
                      start: '2024-05-26T23:18:49Z'
                      end: '2024-01-19T02:12:28Z'
                    data:
                    - {}
                    - {}
                    histogram:
                    - timestamp: '2025-05-11T15:41:12Z'
                      count: 793
                      values: {}
                    - timestamp: '2024-09-14T11:54:08Z'
                      count: 283
                      values: {}
        '400':
          description: Invalid query request body.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                QueryApplicationData400Example:
                  summary: Default queryApplicationData 400 response
                  x-microcks-default: true
                  value:
                    error: example-error
                    message: Endpoint blocked traffic applied blocked on threat.
                    request_id: 34be728a-625b-4e23-9e3a-12d7366cb00d
        '401':
          description: Invalid or missing Bearer token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                QueryApplicationData401Example:
                  summary: Default queryApplicationData 401 response
                  x-microcks-default: true
                  value:
                    error: example-error
                    message: Endpoint blocked traffic applied blocked on threat.
                    request_id: 34be728a-625b-4e23-9e3a-12d7366cb00d
        '403':
          description: Insufficient permissions.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                QueryApplicationData403Example:
                  summary: Default queryApplicationData 403 response
                  x-microcks-default: true
                  value:
                    error: example-error
                    message: Endpoint blocked traffic applied blocked on threat.
                    request_id: 34be728a-625b-4e23-9e3a-12d7366cb00d
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                QueryApplicationData500Example:
                  summary: Default queryApplicationData 500 response
                  x-microcks-default: true
                  value:
                    error: example-error
                    message: Endpoint blocked traffic applied blocked on threat.
                    request_id: 34be728a-625b-4e23-9e3a-12d7366cb00d
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /agg/query/bandwidth:
    post:
      operationId: queryBandwidthData
      summary: Palo Alto Networks Query Bandwidth Utilization Data
      description: Returns aggregated bandwidth utilization metrics across tenants and SASE locations. Supports filtering by location, time range, and traffic direction. Useful for capacity planning and SLA monitoring reports.
      tags:
      - Aggregation Queries
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AggregationQuery'
            examples:
              QueryBandwidthDataRequestExample:
                summary: Default queryBandwidthData request
                x-microcks-default: true
                value:
                  tsg_id: '895182'
                  filter: {}
                  time_range:
                    start: '2025-05-13T00:30:44Z'
                    end: '2025-04-10T14:11:52Z'
                    last: example-last
                  count: 100
                  histogram:
                    field: example-field
                    interval: 1d
                  group_by:
                  - example-group_by_item
                  - example-group_by_item
                  sort:
                  - field: example-field
                    order: desc
      responses:
        '200':
          description: Bandwidth utilization data returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AggregationResponse'
              examples:
                QueryBandwidthData200Example:
                  summary: Default queryBandwidthData 200 response
                  x-microcks-default: true
                  value:
                    total: 137
                    count: 29
                    time_range:
                      start: '2024-05-26T23:18:49Z'
                      end: '2024-01-19T02:12:28Z'
                    data:
                    - {}
                    - {}
                    histogram:
                    - timestamp: '2025-05-11T15:41:12Z'
                      count: 793
                      values: {}
                    - timestamp: '2024-09-14T11:54:08Z'
                      count: 283
                      values: {}
        '400':
          description: Invalid query request body.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                QueryBandwidthData400Example:
                  summary: Default queryBandwidthData 400 response
                  x-microcks-default: true
                  value:
                    error: example-error
                    message: Endpoint blocked traffic applied blocked on threat.
                    request_id: 34be728a-625b-4e23-9e3a-12d7366cb00d
        '401':
          description: Invalid or missing Bearer token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                QueryBandwidthData401Example:
                  summary: Default queryBandwidthData 401 response
                  x-microcks-default: true
                  value:
                    error: example-error
                    message: Endpoint blocked traffic applied blocked on threat.
                    request_id: 34be728a-625b-4e23-9e3a-12d7366cb00d
        '403':
          description: Insufficient permissions.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                QueryBandwidthData403Example:
                  summary: Default queryBandwidthData 403 response
                  x-microcks-default: true
                  value:
                    error: example-error
                    message: Endpoint blocked traffic applied blocked on threat.
                    request_id: 34be728a-625b-4e23-9e3a-12d7366cb00d
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                QueryBandwidthData500Example:
                  summary: Default queryBandwidthData 500 response
                  x-microcks-default: true
                  value:
                    error: example-error
                    message: Endpoint blocked traffic applied blocked on threat.
                    request_id: 34be728a-625b-4e23-9e3a-12d7366cb00d
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /agg/query/license:
    post:
      operationId: queryLicenseData
      summary: Palo Alto Networks Query License Utilization Data
      description: Returns aggregated license utilization data across tenants for all active SASE subscriptions. Supports filtering by product, license type, and TSG. Useful for chargeback reporting and license compliance monitoring.
      tags:
      - Aggregation Queries
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AggregationQuery'
            examples:
              QueryLicenseDataRequestExample:
                summary: Default queryLicenseData request
                x-microcks-default: true
                value:
                  tsg_id: '895182'
                  filter: {}
                  time_range:
                    start: '2025-05-13T00:30:44Z'
                    end: '2025-04-10T14:11:52Z'
                    last: example-last
                  count: 100
                  histogram:
                    field: example-field
                    interval: 1d
                  group_by:
                  - example-group_by_item
                  - example-group_by_item
                  sort:
                  - field: example-field
                    order: desc
      responses:
        '200':
          description: License utilization data returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AggregationResponse'
              examples:
                QueryLicenseData200Example:
                  summary: Default queryLicenseData 200 response
                  x-microcks-default: true
                  value:
                    total: 137
                    count: 29
                    time_range:
                      start: '2024-05-26T23:18:49Z'
                      end: '2024-01-19T02:12:28Z'
                    data:
                    - {}
                    - {}
                    histogram:
                    - timestamp: '2025-05-11T15:41:12Z'
                      count: 793
                      values: {}
                    - timestamp: '2024-09-14T11:54:08Z'
                      count: 283
                      values: {}
        '400':
          description: Invalid query request body.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                QueryLicenseData400Example:
                  summary: Default queryLicenseData 400 response
                  x-microcks-default: true
                  value:
                    error: example-error
                    message: Endpoint blocked traffic applied blocked on threat.
                    request_id: 34be728a-625b-4e23-9e3a-12d7366cb00d
        '401':
          description: Invalid or missing Bearer token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                QueryLicenseData401Example:
                  summary: Default queryLicenseData 401 response
                  x-microcks-default: true
                  value:
                    error: example-error
                    message: Endpoint blocked traffic applied blocked on threat.
                    request_id: 34be728a-625b-4e23-9e3a-12d7366cb00d
        '403':
          description: Insufficient permissions.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                QueryLicenseData403Example:
                  summary: Default queryLicenseData 403 response
                  x-microcks-default: true
                  value:
                    error: example-error
                    message: Endpoint blocked traffic applied blocked on threat.
                    request_id: 34be728a-625b-4e23-9e3a-12d7366cb00d
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                QueryLicenseData500Example:
                  summary: Default queryLicenseData 500 response
                  x-microcks-default: true
                  value:
                    error: example-error
                    message: Endpoint blocked traffic applied blocked on threat.
                    request_id: 34be728a-625b-4e23-9e3a-12d7366cb00d
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  schemas:
    AggregationQuery:
      type: object
      required:
      - tsg_id
      properties:
        tsg_id:
          type: string
          description: Tenant Service Group ID to scope the query. Data from all descendant TSGs within this scope is included.
          example: '895182'
        filter:
          type: object
          description: Key-value filter conditions to apply to the query. Filter keys are data-type specific (e.g., severity, category, app_name).
          additionalProperties:
            type: string
          example: {}
        time_range:
          type: object
          description: Time range for the query.
          properties:
            start:
              type: string
              format: date-time
              description: Query start time (ISO 8601).
              example: '2026-07-01T15:56:30Z'
            end:
              type: string
              format: date-time
              description: Query end time (ISO 8601). Defaults to current time.
              example: '2025-05-05T00:21:55Z'
            last:
              type: string
              description: Relative time range shorthand (e.g., 1h, 24h, 7d, 30d). Mutually exclusive with start/end.
              example: example-last
          example:
            start: '2025-05-13T00:30:44Z'
            end: '2025-04-10T14:11:52Z'
            last: example-last
        count:
          type: integer
          description: Maximum number of result rows to return.
          default: 100
          maximum: 1000
          example: 100
        histogram:
          type: object
          description: Configuration for time-series histogram output. When specified, results are bucketed by time.
          properties:
            field:
              type: string
              description: Timestamp field to use for bucketing.
              example: example-field
            interval:
              type: string
              enum:
              - 1m
              - 5m
              - 15m
              - 1h
              - 6h
              - 1d
              description: Time bucket interval.
              example: 1d
          example:
            field: example-field
            interval: 1d
        group_by:
          type: array
          description: Dimension fields to group results by. Supported values are data-type specific.
          items:
            type: string
          example:
          - example-group_by_item
          - example-group_by_item
        sort:
          type: array
          description: Sort order for results.
          items:
            type: object
            properties:
              field:
                type: string
                description: Field name to sort by.
                example: example-field
              order:
                type: string
                enum:
                - asc
                - desc
                default: desc
                example: desc
          example:
          - field: example-field
            order: desc
    AggregationResponse:
      type: object
      properties:
        total:
          type: integer
          description: Total number of matching records before count limit.
          example: 137
        count:
          type: integer
          description: Number of records returned.
          example: 29
        time_range:
          type: object
          properties:
            start:
              type: string
              format: date-time
              example: '2024-10-13T22:10:28Z'
            end:
              type: string
              format: date-time
              example: '2026-11-26T17:22:41Z'
          example:
            start: '2024-05-26T23:18:49Z'
            end: '2024-01-19T02:12:28Z'
        data:
          type: array
          description: Array of result objects. Schema varies by query type and group_by dimensions.
          items:
            type: object
            additionalProperties: true
          example:
          - {}
          - {}
        histogram:
          type: array
          description: Time-series histogram buckets when histogram configuration was specified in the query.
          items:
            type: object
            properties:
              timestamp:
                type: string
                format: date-time
                example: '2025-02-16T13:06:32Z'
              count:
                type: integer
                example: 432
              values:
                type: object
                additionalProperties: true
                example: {}
          example:
          - timestamp: '2025-05-11T15:41:12Z'
            count: 793
            values: {}
          - timestamp: '2024-09-14T11:54:08Z'
            count: 283
            values: {}
    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: Endpoint blocked traffic applied blocked on threat.
        request_id:
          type: string
          description: Request identifier for support correlation.
          example: 34be728a-625b-4e23-9e3a-12d7366cb00d
  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.