openapi: 3.1.0
info:
  title: Palo Alto Networks SASE Aggregate Monitoring API
  description: >-
    SASE Aggregate Monitoring API for multi-tenant visibility and telemetry.
    Provides aggregated query capabilities across threat, URL, application,
    bandwidth, and license data for SASE-managed tenants. Designed for
    managed service providers and large enterprise deployments where
    operators need cross-tenant visibility in a single query. Supports
    histogram aggregations, group-by dimensions, and flexible filtering
    to power dashboards and compliance reporting workflows.
  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.sase.paloaltonetworks.com/mt/monitor/v1
  description: SASE Aggregate Monitoring API production server.
security:
- oauth2Bearer: []
tags:
- name: Aggregation Queries
  description: Multi-tenant aggregated data queries.
- name: Tenants
  description: Tenant hierarchy visibility.
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: &id001 {}
                  time_range: &id002
                    start: '2025-05-13T00:30:44Z'
                    end: '2025-04-10T14:11:52Z'
                    last: example-last
                  count: 100
                  histogram: &id003
                    field: example-field
                    interval: 1d
                  group_by: &id004
                  - example-group_by_item
                  - example-group_by_item
                  sort: &id005
                  - 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: &id006
                      start: '2024-05-26T23:18:49Z'
                      end: '2024-01-19T02:12:28Z'
                    data: &id007
                    - {}
                    - {}
                    histogram: &id008
                    - 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: *id001
                  time_range: *id002
                  count: 100
                  histogram: *id003
                  group_by: *id004
                  sort: *id005
      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: *id006
                    data: *id007
                    histogram: *id008
        '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: *id001
                  time_range: *id002
                  count: 100
                  histogram: *id003
                  group_by: *id004
                  sort: *id005
      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: *id006
                    data: *id007
                    histogram: *id008
        '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: *id001
                  time_range: *id002
                  count: 100
                  histogram: *id003
                  group_by: *id004
                  sort: *id005
      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: *id006
                    data: *id007
                    histogram: *id008
        '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: *id001
                  time_range: *id002
                  count: 100
                  histogram: *id003
                  group_by: *id004
                  sort: *id005
      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: *id006
                    data: *id007
                    histogram: *id008
        '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
  /tenants:
    get:
      operationId: listMonitoringTenants
      summary: Palo Alto Networks Get Tenant Hierarchy
      description: >-
        Returns the tenant hierarchy accessible to the authenticated
        service account within the Aggregate Monitoring scope. Use this
        endpoint to enumerate the TSG IDs available for use in aggregation
        queries.
      tags:
      - Tenants
      parameters:
      - name: tsg_id
        in: query
        description: >-
          Root TSG ID from which to return the hierarchy. Defaults to
          the TSG of the authenticated service account.
        schema:
          type: string
        example: '699512'
      responses:
        '200':
          description: Tenant hierarchy returned.
          content:
            application/json:
              schema:
                type: object
                properties:
                  total:
                    type: integer
                    description: Total number of tenants in the hierarchy.
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/TenantSummary'
              examples:
                ListMonitoringTenants200Example:
                  summary: Default listMonitoringTenants 200 response
                  x-microcks-default: true
                  value:
                    total: 147
                    items:
                    - tsg_id: '301496'
                      display_name: Carlos Wilson
                      parent_id: '264676'
                      depth: 182
                      child_count: 779
                    - tsg_id: '301496'
                      display_name: Carlos Wilson
                      parent_id: '264676'
                      depth: 182
                      child_count: 779
        '401':
          description: Invalid or missing Bearer token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                ListMonitoringTenants401Example:
                  summary: Default listMonitoringTenants 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:
                ListMonitoringTenants403Example:
                  summary: Default listMonitoringTenants 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:
                ListMonitoringTenants500Example:
                  summary: Default listMonitoringTenants 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:
  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.
  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: *id001
        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: *id002
        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: *id003
        group_by:
          type: array
          description: >-
            Dimension fields to group results by. Supported values are
            data-type specific.
          items:
            type: string
          example: *id004
        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: *id005
    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: *id006
        data:
          type: array
          description: >-
            Array of result objects. Schema varies by query type and
            group_by dimensions.
          items:
            type: object
            additionalProperties: true
          example: *id007
        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: *id008
    TenantSummary:
      type: object
      properties:
        tsg_id:
          type: string
          description: Tenant Service Group ID.
          example: '301496'
        display_name:
          type: string
          description: TSG display name.
          example: Carlos Wilson
        parent_id:
          type: string
          description: Parent TSG ID.
          example: '264676'
        depth:
          type: integer
          description: Depth in the hierarchy (0 for root).
          example: 182
        child_count:
          type: integer
          description: Number of direct child TSGs.
          example: 779
    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