Prisma Access Insights API

openapi: 3.1.0
info:
  title: Palo Alto Networks Prisma Access Insights API
  description: >-
    REST API for querying the health and performance of Prisma Access network
    deployments. Available across three API versions (v1.0, v2.0, v3.0),
    the Insights API supports data resource queries for tunnel status, bandwidth
    utilization, connected user analytics, site health, accelerated application
    performance, and PAB events. Designed for both cloud-managed (TSG-based)
    and Panorama-managed Prisma Access customers.
  version: '3.0'
  contact:
    name: Palo Alto Networks Support
    url: https://www.paloaltonetworks.com/services/support
  termsOfService: https://www.paloaltonetworks.com/legal
externalDocs:
  description: Prisma Access Insights API Documentation
  url: https://pan.dev/access/api/insights/

servers:
- url: https://api.sase.paloaltonetworks.com
  description: Prisma SASE Production API Server

tags:
- name: Custom Queries
  description: Execute custom data resource queries with filters and aggregations
- name: Data Exports
  description: Export data resource results for external processing

- name: Data Resources
  description: Query Prisma Access deployment health and performance data resources
security:
- bearerAuth: []

paths:
  /insights/v3.0/resource/query/{resource_name}:
    post:
      operationId: queryDataResource
      summary: Palo Alto Networks Query a Data Resource
      description: >-
        Query a named Prisma Access data resource for health, performance, or
        analytics data. Supports filtering by time range, site, user, application,
        and other dimensions. Returns paginated results with optional histogram
        and aggregation support.
      tags:
      - Data Resources
      parameters:
      - $ref: '#/components/parameters/ResourceName'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DataResourceQuery'
            examples:
              QueryDataResourceRequestExample:
                summary: Default queryDataResource request
                x-microcks-default: true
                value:
                  query: &id001
                    properties:
                      time_range:
                        type: RELATIVE
                        value:
                          from: '2024-06-20T21:24:24Z'
                          to: '2025-04-19T12:09:38Z'
                        last:
                          units: DAYS
                          value: 963
                      filter:
                        operator: OR
                        rules:
                        - {}
                        - {}
                  count: 100
                  histogram: &id002
                    property: example-property
                    enabledGranularity: 15_MIN
                  group_by: &id003
                  - example-group_by_item
                  sort: &id004
                    order: asc
                    property: example-property
      responses:
        '200':
          description: Data resource query results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DataResourceResponse'
              examples:
                QueryDataResource200Example:
                  summary: Default queryDataResource 200 response
                  x-microcks-default: true
                  value:
                    header: &id005
                      requestId: '824026'
                      status: success
                      timestamp: '2024-09-25T11:15:56Z'
                    data: &id006
                    - {}
                    count: 586
                    pagination: &id007
                      offset: 507
                      limit: 195
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'

      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /insights/v3.0/resource/custom-query:
    post:
      operationId: executeCustomQuery
      summary: Palo Alto Networks Execute a Custom Data Resource Query
      description: >-
        Execute a flexible custom query against Prisma Access monitoring data
        with user-defined filters, groupings, and time ranges. Supports
        advanced analytics use cases that require custom dimension combinations.
      tags:
      - Custom Queries
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CustomQuery'
            examples:
              ExecuteCustomQueryRequestExample:
                summary: Default executeCustomQuery request
                x-microcks-default: true
                value:
                  resource: example-resource
                  query:
                    query: *id001
                    count: 100
                    histogram: *id002
                    group_by: *id003
                    sort: *id004
      responses:
        '200':
          description: Custom query results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DataResourceResponse'
              examples:
                ExecuteCustomQuery200Example:
                  summary: Default executeCustomQuery 200 response
                  x-microcks-default: true
                  value:
                    header: *id005
                    data: *id006
                    count: 586
                    pagination: *id007
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '500':
          $ref: '#/components/responses/InternalServerError'

      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /insights/v3.0/resource/export/{resource_name}:
    post:
      operationId: exportDataResource
      summary: Palo Alto Networks Export Data Resource Results
      description: >-
        Export data resource query results for bulk retrieval and external
        processing. Returns a job ID that can be used to check export status
        and retrieve the exported data file.
      tags:
      - Data Exports
      parameters:
      - $ref: '#/components/parameters/ResourceName'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DataResourceQuery'
            examples:
              ExportDataResourceRequestExample:
                summary: Default exportDataResource request
                x-microcks-default: true
                value:
                  query: *id001
                  count: 100
                  histogram: *id002
                  group_by: *id003
                  sort: *id004
      responses:
        '202':
          description: Export job accepted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExportJobResponse'
              examples:
                ExportDataResource202Example:
                  summary: Default exportDataResource 202 response
                  x-microcks-default: true
                  value:
                    job_id: '828854'
                    status: PENDING
                    submitted_at: '2025-09-08T01:27:01Z'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '500':
          $ref: '#/components/responses/InternalServerError'

      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /insights/v3.0/resource/export/{job_id}/status:
    get:
      operationId: getExportJobStatus
      summary: Palo Alto Networks Get Export Job Status
      description: >-
        Check the status of a previously submitted data resource export job.
        Returns the current status and a download URL when the export completes.
      tags:
      - Data Exports
      parameters:
      - name: job_id
        in: path
        required: true
        description: Export job identifier returned when the export was submitted
        schema:
          type: string
        example: '202649'
      responses:
        '200':
          description: Export job status
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExportJobStatus'
              examples:
                GetExportJobStatus200Example:
                  summary: Default getExportJobStatus 200 response
                  x-microcks-default: true
                  value:
                    job_id: '541044'
                    status: COMPLETED
                    download_url: https://login.acme-systems.org/ed2530
                    expires_at: '2025-08-14T12:57:10Z'
                    error_message: example-error_message
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'

      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >-
        OAuth 2.0 access token obtained from
        https://auth.apps.paloaltonetworks.com/oauth2/access_token using
        Client ID and Client Secret credentials scoped to the Tenant Service Group.

  parameters:
    ResourceName:
      name: resource_name
      in: path
      required: true
      description: >-
        The name of the data resource to query. Common resources include
        `tunnel_status`, `connected_users`, `site_bandwidth`, `app_experience`,
        `pa_browser_events`, `gp_mobile_users`, `ipsec_tunnels`, `bgp_routes`.
      schema:
        type: string
        enum:
        - tunnel_status
        - connected_users
        - site_bandwidth
        - app_experience
        - pa_browser_events
        - gp_mobile_users
        - ipsec_tunnels
        - bgp_routes
        - alerts
        - sdwan_sites

  schemas:
    DataResourceQuery:
      type: object
      description: Query parameters for a data resource request
      properties:
        query:
          type: object
          description: Query definition including filters and time range
          properties:
            properties:
              type: object
              description: Property filters for the query
              properties:
                time_range:
                  $ref: '#/components/schemas/TimeRange'
                filter:
                  $ref: '#/components/schemas/QueryFilter'
              example:
                time_range:
                  type: ABSOLUTE
                  value:
                    from: '2026-04-13T06:13:40Z'
                    to: '2026-09-13T19:54:05Z'
                  last:
                    units: HOURS
                    value: 315
                filter:
                  operator: AND
                  rules:
                  - {}
          example: *id001
        count:
          type: integer
          description: Maximum number of results to return
          minimum: 1
          maximum: 1000
          default: 100
          example: 100
        histogram:
          type: object
          description: Histogram aggregation configuration
          properties:
            property:
              type: string
              description: Property to aggregate over
              example: example-property
            enabledGranularity:
              type: string
              enum:
              - 15_MIN
              - 1_HOUR
              - 1_DAY
              description: Time granularity for histogram buckets
              example: 1_DAY
          example: *id002
        group_by:
          type: array
          description: Properties to group results by
          items:
            type: string
          example: *id003
        sort:
          type: object
          description: Sort configuration for results
          properties:
            order:
              type: string
              enum:
              - asc
              - desc
              example: desc
            property:
              type: string

              example: example-property
          example: *id004
    TimeRange:
      type: object
      description: Time range specification for the query
      required:
      - type
      properties:
        type:
          type: string
          description: Type of time range (absolute or relative)
          enum:
          - ABSOLUTE
          - RELATIVE
          example: RELATIVE
        value:
          type: object
          description: Time range value (required for ABSOLUTE type)
          properties:
            from:
              type: string
              format: date-time
              description: Start of the time range (ISO 8601)
              example: '2024-08-09T03:25:39Z'
            to:
              type: string
              format: date-time
              description: End of the time range (ISO 8601)
              example: '2025-11-03T11:39:36Z'
          example:
            from: '2024-09-24T21:35:19Z'
            to: '2026-05-23T17:35:52Z'
        last:
          type: object
          description: Relative time range (required for RELATIVE type)
          properties:
            units:
              type: string
              enum:
              - HOURS
              - DAYS
              - WEEKS
              description: Unit of time for relative range
              example: WEEKS
            value:
              type: integer
              description: Number of units for relative range

              example: 651
          example:
            units: WEEKS
            value: 233
    QueryFilter:
      type: object
      description: Filter criteria for the data resource query
      properties:
        operator:
          type: string
          description: Logical operator for combining filter rules
          enum:
          - AND
          - OR
          example: OR
        rules:
          type: array
          description: List of filter rules
          items:
            type: object
            properties:
              property:
                type: string
                description: Property name to filter on
                example: example-property
              operator:
                type: string
                description: Comparison operator
                enum:
                - equals
                - not_equals
                - contains
                - in
                - not_in
                - greater_than
                - less_than
                example: greater_than
              values:
                type: array
                description: Values to match against
                items:
                  type: string

                example:
                - example-values_item
                - example-values_item
          example:
          - property: example-property
            operator: in
            values:
            - example-values_item
          - property: example-property
            operator: greater_than
            values:
            - example-values_item
    CustomQuery:
      type: object
      description: Custom query definition with flexible filters
      properties:
        resource:
          type: string
          description: Data resource to query
          example: example-resource
        query:
          $ref: '#/components/schemas/DataResourceQuery'

    DataResourceResponse:
      type: object
      description: Response containing data resource query results
      properties:
        header:
          type: object
          description: Response metadata
          properties:
            requestId:
              type: string
              description: Unique request identifier
              example: '659112'
            status:
              type: string
              enum:
              - success
              - failed
              - partial
              example: partial
            timestamp:
              type: string
              format: date-time
              example: '2024-10-10T14:49:56Z'
          example: *id005
        data:
          type: array
          description: Array of result records
          items:
            type: object
            additionalProperties: true
          example: *id006
        count:
          type: integer
          description: Total number of records matching the query
          example: 586
        pagination:
          type: object
          description: Pagination information
          properties:
            offset:
              type: integer
              description: Current result offset
              example: 985
            limit:
              type: integer
              description: Page size

              example: 592
          example: *id007
    ExportJobResponse:
      type: object
      description: Response from a submitted export job
      properties:
        job_id:
          type: string
          description: Unique identifier for the export job
          example: '828854'
        status:
          type: string
          enum:
          - PENDING
          - RUNNING
          - COMPLETED
          - FAILED
          description: Current job status
          example: PENDING
        submitted_at:
          type: string
          format: date-time
          description: Job submission timestamp

          example: '2025-09-08T01:27:01Z'
    ExportJobStatus:
      type: object
      description: Status and result of an export job
      properties:
        job_id:
          type: string
          description: Export job identifier
          example: '541044'
        status:
          type: string
          enum:
          - PENDING
          - RUNNING
          - COMPLETED
          - FAILED
          description: Current job status
          example: COMPLETED
        download_url:
          type: string
          format: uri
          description: Signed URL to download the export file (available when COMPLETED)
          example: https://login.acme-systems.org/ed2530
        expires_at:
          type: string
          format: date-time
          description: Expiration time of the download URL
          example: '2025-08-14T12:57:10Z'
        error_message:
          type: string
          description: Error description if the job failed

          example: example-error_message
    ErrorResponse:
      type: object
      description: Standard error response structure
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              description: Machine-readable error code
              example: example-code
            message:
              type: string
              description: Human-readable error description

              example: Malware firewall blocked threat on policy.
          example:
            code: example-code
            message: Network network network network malware monitoring traffic monitoring investigation on suspicious.
  responses:
    BadRequest:
      description: Bad request — invalid query parameters or request body
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Unauthorized:
      description: Unauthorized — missing or invalid access token
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Forbidden:
      description: Forbidden — insufficient permissions for the requested resource
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    NotFound:
      description: Not found — the requested resource or job does not exist
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    InternalServerError:
      description: Internal server error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'