> ## Documentation Index
> Fetch the complete documentation index at: https://docs.opal.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Run an ad-hoc OpalQuery

> Runs an ad-hoc OpalQuery and returns the results. Currently supports NODE queries (users, resources, groups). This endpoint is only available to our OpalQuery beta group. Please contact Opal support if you'd like to be added to the beta.



## OpenAPI

````yaml https://app.opal.dev/openapi.yaml post /queries/run
openapi: 3.1.0
info:
  contact:
    email: hello@opal.dev
    name: Opal Team
    url: https://www.opal.dev/
  description: >-
    The Opal API is a RESTful API that allows you to interact with the Opal
    Security platform programmatically.
  title: Opal API
  version: '1.0'
servers:
  - description: Production
    url: https://api.opal.dev/v1
security: []
tags:
  - name: access-rules
    description: Operations related to access rules
  - name: apps
    description: Operations related to apps
  - name: bundles
    description: Operations related to bundles
  - name: configuration-templates
    description: Operations related to configuration templates
  - name: delegations
    description: Operations related to request reviewer delegations
  - name: event-streams
    description: Operations related to event streaming connections
  - name: events
    description: Operations related to events
  - name: groups
    description: Operations related to groups
  - name: group-bindings
    description: Operations related to group bindings
  - name: idp-group-mappings
    description: Operations related to IDP group mappings
  - name: message-channels
    description: Operations related to message channels
  - name: non-human-identities
    description: Operations related to non-human identities
  - name: on-call-schedules
    description: Operations related to on-call schedules
  - name: opal-queries
    description: Operations related to OpalQuery
  - name: owners
    description: Operations related to owners
  - name: requests
    description: Operations related to requests
  - name: resources
    description: Operations related to resources
  - name: sessions
    description: Operations related to sessions
  - name: tags
    description: Operations related to tags
  - name: tokens
    description: Operations related to API tokens
  - name: uars
    description: Operations related to UARs
  - name: users
    description: Operations related to users
paths:
  /queries/run:
    post:
      tags:
        - opal-queries
      summary: Run an ad-hoc OpalQuery
      description: >-
        Runs an ad-hoc OpalQuery and returns the results. Currently supports
        NODE queries (users, resources, groups). This endpoint is only available
        to our OpalQuery beta group. Please contact Opal support if you'd like
        to be added to the beta.
      operationId: runOpalQuery
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RunOpalQueryRequest'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OpalQueryResults'
          description: The results of the OpalQuery.
      security:
        - BearerAuth: []
components:
  schemas:
    RunOpalQueryRequest:
      description: >-
        Request body for running an ad-hoc OpalQuery. The `type` field
        determines which query schema applies.
      oneOf:
        - $ref: '#/components/schemas/OpalNodeQuery'
      discriminator:
        propertyName: type
        mapping:
          NODE:
            $ref: '#/components/schemas/OpalNodeQuery'
    OpalQueryResults:
      description: >-
        Paginated results of an OpalQuery. The `type` field discriminates which
        result schema applies and mirrors the `type` field on the request.
      oneOf:
        - $ref: '#/components/schemas/OpalNodeQueryResults'
      discriminator:
        propertyName: type
        mapping:
          NODE:
            $ref: '#/components/schemas/OpalNodeQueryResults'
    OpalNodeQuery:
      type: object
      required:
        - type
      description: >-
        Request body for a NODE-type OpalQuery. Returns entities (users,
        resources, groups) matching the given filters.
      example:
        type: NODE
        query:
          nodeFilters:
            entityTypes:
              - RESOURCE
            entityTag:
              key: env
              value: prod
          accessFilters:
            isAccessibleBy:
              entityTypes:
                - USER
              entityTag:
                key: contractor
        first: 50
      properties:
        type:
          type: string
          enum:
            - NODE
        query:
          $ref: '#/components/schemas/OpalNodeQueryBody'
        first:
          type: integer
          description: Maximum number of results to return. Defaults to 200.
          example: 200
        after:
          type: string
          description: Cursor from a previous response to fetch the next page of results.
          example: 29827fb8-f2dd-4e80-9576-28e31e9934ac
    OpalNodeQueryResults:
      type: object
      required:
        - type
        - edges
        - pageInfo
      description: >-
        Paginated results of a NODE-type OpalQuery — one edge per matched entity
        (user, resource, or group).
      properties:
        type:
          type: string
          enum:
            - NODE
        edges:
          type: array
          description: List of matched entities.
          items:
            $ref: '#/components/schemas/OpalQueryResultEdge'
        pageInfo:
          $ref: '#/components/schemas/PageInfo'
    OpalNodeQueryBody:
      type: object
      description: The filter body for a NODE-type OpalQuery.
      properties:
        nodeFilters:
          $ref: '#/components/schemas/AccessEntityFilters'
        accessFilters:
          $ref: '#/components/schemas/AccessRelationshipFilters'
    OpalQueryResultEdge:
      type: object
      required:
        - node
        - cursor
      description: >-
        A single result edge from an OpalQuery, containing the matched entity
        and its pagination cursor.
      properties:
        node:
          $ref: '#/components/schemas/OpalQueryResultNode'
        cursor:
          type: string
          description: Opaque cursor for this entity, used for pagination.
    PageInfo:
      type: object
      required:
        - hasNextPage
        - endCursor
        - hasPreviousPage
        - startCursor
      properties:
        hasNextPage:
          type: boolean
          description: Whether there are more items after the end cursor
        endCursor:
          type: string
          description: The cursor to continue pagination forwards
        hasPreviousPage:
          type: boolean
          description: Whether there are more items before the start cursor
        startCursor:
          type: string
          description: The cursor to continue pagination backwards
    AccessEntityFilters:
      type: object
      description: >-
        Filters for matching entities by type, name, tag, IDs, connections, or
        access levels. Supports recursive logical composition via allOf/anyOf.
      properties:
        entityTypes:
          type: array
          description: >-
            Filter by entity type. Only RESOURCE, GROUP, and USER are queryable
            via OpalQuery.
          items:
            type: string
            enum:
              - RESOURCE
              - GROUP
              - USER
        entityItemTypes:
          type: array
          description: Filter by entity item types.
          items:
            $ref: '#/components/schemas/EntityItemTypeEnum'
        entityName:
          $ref: '#/components/schemas/EntityNameFilter'
        entityTag:
          $ref: '#/components/schemas/EntityTagFilter'
        entityIDs:
          type: array
          description: Filter by specific entity UUIDs.
          items:
            type: string
            format: uuid
        importedFromApp:
          type: array
          description: Filter by app IDs from which returned nodes will be imported from.
          items:
            type: string
            format: uuid
        roleRemoteIds:
          type: array
          description: >-
            Filter by role remote IDs. Can only be applied within a hasAccessTo
            clause.
          items:
            type: string
        roleNames:
          type: array
          description: >-
            Filter by role display names (e.g. "Admin", "Read"). Can only be
            applied within a hasAccessTo clause.
          items:
            type: string
        allOf:
          type: array
          description: |
            A list of nested filters that must all match (logical AND). Each
             item has the same shape as this object — scalar fields like
             `entityTypes` or `entityTag`, and can further nest `allOf`,
             `anyOf`, or `not`.
          items:
            $ref: '#/components/schemas/AccessEntityFilters'
        anyOf:
          type: array
          description: |
            A list of nested filters where at least one must match (logical
             OR). Each item has the same shape as this object.
          items:
            $ref: '#/components/schemas/AccessEntityFilters'
        not:
          description: >
            Excludes entities matching the embedded filter (logical NOT). Pass a
            filter object with the same shape as this one — typically a single
            scalar field, like `{not: {entityTypes: ["RESOURCE"]}}` to exclude
            resources.
          type: object
          x-go-type: AccessEntityFilters
    AccessRelationshipFilters:
      type: object
      description: >
        Filters the returned nodes by the access edges connected to them. When
        `isAccessibleBy` and `hasAccessTo` are provided, the returned nodes must
        satisfy both edge constraints simultaneously.
      properties:
        isAccessibleBy:
          $ref: '#/components/schemas/AccessEntityFilters'
          description: >-
            Inbound-edge filter. The returned node must be accessible by at
            least one entity matching this filter.
        hasAccessTo:
          $ref: '#/components/schemas/AccessEntityFilters'
          description: >-
            Outbound-edge filter. The returned node must have access to at least
            one entity matching this filter.
    OpalQueryResultNode:
      type: object
      required:
        - id
        - name
        - entityType
        - entityItemType
      description: A matched entity from an OpalQuery result.
      properties:
        id:
          type: string
          format: uuid
          description: The entity's unique identifier.
        name:
          type: string
          description: The display name of the entity.
        entityType:
          type: string
          enum:
            - USER
            - GROUP
            - RESOURCE
          description: The top-level entity type.
        entityItemType:
          $ref: '#/components/schemas/EntityItemTypeEnum'
    EntityItemTypeEnum:
      description: Granular subtype of an entity.
      enum:
        - USER
        - SERVICE_USER
        - ACTIVE_DIRECTORY_GROUP
        - AWS_SSO_GROUP
        - DUO_GROUP
        - GIT_HUB_TEAM
        - GIT_LAB_GROUP
        - GOOGLE_GROUPS_GROUP
        - GOOGLE_GROUPS_GKE_GROUP
        - LDAP_GROUP
        - OKTA_GROUP
        - OKTA_GROUP_RULE
        - TAILSCALE_GROUP
        - TWINGATE_GROUP
        - TWINGATE_GROUP_SYNCED
        - OPAL_GROUP
        - OPAL_ACCESS_RULE
        - AZURE_AD_SECURITY_GROUP
        - AZURE_AD_MICROSOFT_365_GROUP
        - CONNECTOR_GROUP
        - SNOWFLAKE_ROLE
        - WORKDAY_USER_SECURITY_GROUP
        - DATABRICKS_ACCOUNT_GROUP
        - AWS_IAM_ROLE
        - AWS_EC2_INSTANCE
        - AWS_EKS_CLUSTER
        - AWS_RDS_POSTGRES_INSTANCE
        - AWS_RDS_POSTGRES_CLUSTER
        - AWS_RDS_MYSQL_INSTANCE
        - AWS_RDS_MYSQL_CLUSTER
        - AWS_ACCOUNT
        - AWS_SSO_PERMISSION_SET
        - AZURE_MANAGEMENT_GROUP
        - AZURE_RESOURCE_GROUP
        - AZURE_SUBSCRIPTION
        - AZURE_VIRTUAL_MACHINE
        - AZURE_STORAGE_ACCOUNT
        - AZURE_STORAGE_CONTAINER
        - AZURE_SQL_SERVER
        - AZURE_SQL_MANAGED_INSTANCE
        - AZURE_SQL_DATABASE
        - AZURE_SQL_MANAGED_DATABASE
        - AZURE_USER_ASSIGNED_MANAGED_Identity
        - AZURE_ENTRA_ID_ROLE
        - AZURE_ENTERPRISE_APP
        - CUSTOM
        - CUSTOM_CONNECTOR
        - GCP_ORGANIZATION
        - GCP_BUCKET
        - GCP_COMPUTE_INSTANCE
        - GCP_BIG_QUERY_DATASET
        - GCP_BIG_QUERY_TABLE
        - GCP_FOLDER
        - GCP_GKE_CLUSTER
        - GCP_PROJECT
        - GCP_CLOUD_SQL_POSTGRES_INSTANCE
        - GCP_CLOUD_SQL_MYSQL_INSTANCE
        - GCP_SERVICE_ACCOUNT
        - GIT_HUB_REPO
        - GIT_HUB_ORG_ROLE
        - GIT_LAB_PROJECT
        - GOOGLE_WORKSPACE_ROLE
        - MONGO_INSTANCE
        - MONGO_ATLAS_INSTANCE
        - OKTA_APP
        - OKTA_ROLE
        - OPAL_ROLE
        - OPAL_SCOPED_ROLE
        - PAGERDUTY_ROLE
        - TAILSCALE_SSH
        - TWINGATE_RESOURCE
        - SALESFORCE_PERMISSION_SET
        - SALESFORCE_PROFILE
        - SALESFORCE_ROLE
        - SNOWFLAKE_DATABASE
        - SNOWFLAKE_SCHEMA
        - SNOWFLAKE_TABLE
        - WORKDAY_ROLE
        - MYSQL_INSTANCE
        - MARIADB_INSTANCE
        - POSTGRES_INSTANCE
        - TELEPORT_ROLE
        - DATABRICKS_ACCOUNT_SERVICE_PRINCIPAL
        - ILEVEL_ADVANCED_ROLE
      example: OPAL_ROLE
      type: string
    EntityNameFilter:
      type: object
      required:
        - stringMatchType
        - string
      description: Filters entities by name using a string match strategy.
      properties:
        stringMatchType:
          $ref: '#/components/schemas/StringMatchType'
        string:
          type: string
          description: The string value to match against the entity name.
          example: engineering
    EntityTagFilter:
      type: object
      required:
        - key
      description: >-
        Filters entities by a tag key/value pair, optionally scoped to a
        connection.
      properties:
        key:
          type: string
          description: The tag key to filter by.
          example: team
        value:
          type: string
          description: >-
            The tag value to filter by. If omitted, matches any value for the
            given key.
          example: platform
        connectionId:
          type: string
          format: uuid
          description: If specified, filters by tags associated with this connection.
    StringMatchType:
      type: string
      description: How to match a string value against entity names.
      enum:
        - CONTAINS
        - EQUALS
        - STARTS_WITH
        - ENDS_WITH
  securitySchemes:
    BearerAuth:
      scheme: bearer
      type: http

````