ALTR Query Audits API API

openapi: 3.2.0
info:
  description: 'The Query Audits API is used to get query audits generated by ALTR.

    ALTR generates a query audit when a query that accesses governed data is executed.'
  title: Query Audits Query Audits API API
  contact: {}
  version: 1.1.0
servers:
- url: https://api.live.altr.com/v1/query-audits
tags:
- name: Query Audits API
paths:
  /results/{search_uuid}:
    get:
      security:
      - BasicAuth: []
      description: This endpoint retrieves the results of a search using the `search_uuid` provided by the /search endpoint. The results are paginated and can be retrieved using the `next_page_token` provided in the response.
      tags:
      - Query Audits API
      summary: Get the results of a search using the `search_uuid`.
      parameters:
      - example: 123e4567-e89b-12d3-a456-426614174000
        description: '`search_uuid` received by /search endpoint.'
        name: search_uuid
        in: path
        required: true
        schema:
          type: string
      - example: ARpLpuKth8RwkdlQA2ktpaV/uJoOyM1EKldHyjKTLbagIrIWP1PLXiO67UyWew==
        description: The token to retrieve the next page of results.
        name: next_page_token
        in: query
        schema:
          type: string
      - description: Limit the number of results returned.
        name: limit
        in: query
        schema:
          type: integer
          default: 250
          maximum: 250
          minimum: 1
      responses:
        '200':
          description: Search complete. Results are ready.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/main.GetResultOutput'
        '202':
          description: Search not complete. Results are not ready.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/main.GetResultOutput'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Search UUID not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /search:
    post:
      security:
      - BasicAuth: []
      description: 'This endpoint triggers a search for query audits. Chaining query parameter filters as `AND` operations.

        The `search_uuid` that is returned expires after 30 days.'
      tags:
      - Query Audits API
      summary: Trigger search using various filters.
      parameters:
      - description: The maximum number of items to return.
        name: limit
        in: query
        schema:
          type: integer
          default: 10000
          maximum: 100000
          minimum: 1
      - description: The number of items to skip.
        name: offset
        in: query
        schema:
          type: integer
          default: 0
          minimum: 0
      - example: '2024-11-23T17:51:35.000Z'
        description: Queries that ended before this time will not be returned. Must be provided as a UTC timestamp in valid RFC3339 format. Default is 24 hours ago.
        name: from_date_time
        in: query
        schema:
          type: string
      - example: '2024-11-24T17:51:35.000Z'
        description: Queries that ended after this time will not be returned. Must be provided as a UTC timestamp in valid RFC3339 format. Default is now.
        name: to_date_time
        in: query
        schema:
          type: string
      - example: BI_SERVICE_ROLE
        description: The role that executed the query. Case-insensitive.
        name: executing_role
        in: query
        schema:
          type: string
      - example: BI_SERVICE_USER
        description: The user that executed the query. Case-insensitive.
        name: executing_user
        in: query
        schema:
          type: string
      - example: 01d89caa-080e-3b34-0000-se59220b6656
        description: The ID of the query. Case-insensitive.
        name: query_id
        in: query
        schema:
          type: string
      - example: PII_TAG
        description: The policy tag name to filter by. Case-insensitive.
        name: policy_tag_name
        in: query
        schema:
          type: string
      - example: EMAIL
        description: The policy tag value to filter by. Case-insensitive.
        name: policy_tag_value
        in: query
        schema:
          type: string
      - example: EXAMPLE_DB
        description: The policy column database name to filter by. Case-insensitive.
        name: policy_column_database_name
        in: query
        schema:
          type: string
      - example: EXAMPLE_SCHEMA
        description: The policy column schema name to filter by. Case-insensitive.
        name: policy_column_schema_name
        in: query
        schema:
          type: string
      - example: EXAMPLE_TABLE
        description: The policy column table name to filter by. Case-insensitive.
        name: policy_column_table_name
        in: query
        schema:
          type: string
      - description: The policy column name to filter by. Case-insensitive.
        name: policy_column_name
        in: query
        schema:
          type: string
      - description: The order by clause for the query. Case-insensitive.
        name: order_by
        in: query
        schema:
          type: string
          enum:
          - asc
          - desc
          default: desc
      - description: The column to sort by. Case-insensitive.
        name: sort_by
        in: query
        schema:
          type: string
          enum:
          - event_time
          - rows_accessed
          default: event_time
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/management.TriggerSearchOutput'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/main.SearchRequestDoc'
        description: Optional filter-tree expression body. The 'filter' field accepts the same audit-filter DSL used by dam-alerting threshold rules; when present it is AND-composed with the query-string filters above. Omit the body entirely for the legacy query-param-only behavior. The 'timezone' field (IANA name) is required when the filter contains a time_of_day dimension and forbidden otherwise. Children of and/or nodes are themselves FilterNode subtrees with the same shape; the docs flatten the inner level to a generic object to keep Swagger UI happy.
components:
  schemas:
    ErrorResponse:
      type: object
      properties:
        error:
          type: string
    management.QueryAudit:
      type: object
      properties:
        event_id:
          type: string
          x-order: '0'
        client_id:
          type: string
          x-order: '1'
        event_version:
          type: string
          x-order: '2'
        event_name:
          type: string
          x-order: '3'
        event_source:
          type: string
          x-order: '4'
        event_time:
          type: integer
          x-order: '5'
        user_identity:
          allOf:
          - $ref: '#/components/schemas/management.UserIdentity'
          x-order: '6'
        event_details:
          allOf:
          - $ref: '#/components/schemas/management.EventDetails'
          x-order: '7'
    auditfilter.KeyEqValue:
      type: object
      required:
      - key
      - value
      properties:
        key:
          type: string
          maxLength: 256
        value:
          type: string
          maxLength: 256
    management.EventDetails:
      type: object
      properties:
        actor:
          allOf:
          - $ref: '#/components/schemas/management.Actor'
          x-order: '0'
        account:
          allOf:
          - $ref: '#/components/schemas/management.Account'
          x-order: '1'
        query:
          allOf:
          - $ref: '#/components/schemas/management.Query'
          x-order: '2'
        result:
          allOf:
          - $ref: '#/components/schemas/management.Result'
          x-order: '3'
    main.FilterNodeDoc:
      type: object
      required:
      - op
      properties:
        between:
          $ref: '#/components/schemas/auditfilter.BetweenValue'
        children:
          description: 'Children is required for op=and|or. Each entry is a nested FilterNode

            with the same shape as this object. Typed as []object here only to break

            the recursive $ref that older Swagger UI cannot resolve.'
          type: array
          items:
            type: object
            additionalProperties: {}
        dimension:
          $ref: '#/components/schemas/auditfilter.Dimension'
        key_eq:
          $ref: '#/components/schemas/auditfilter.KeyEqValue'
        list_value:
          type: array
          minItems: 1
          items:
            type: string
        number_value:
          type: number
        op:
          $ref: '#/components/schemas/auditfilter.Op'
        range:
          $ref: '#/components/schemas/auditfilter.RangeValue'
        string_value:
          type: string
          maxLength: 1024
    management.TagAuditTimeDecision:
      type: object
      properties:
        tag_name:
          type: string
          x-order: '0'
        tag_value:
          type: string
          x-order: '1'
        applied_policy:
          allOf:
          - $ref: '#/components/schemas/management.AppliedPolicy'
          x-order: '2'
        policy_info:
          type: array
          items:
            $ref: '#/components/schemas/management.PolicyInfo'
          x-order: '3'
    management.AppliedPolicy:
      type: object
      properties:
        id:
          type: integer
          x-order: '0'
        name:
          type: string
          x-order: '1'
        type:
          type: string
          x-order: '2'
        masking_type:
          type: string
          x-order: '3'
        decision_type:
          type: string
          x-order: '4'
        reason:
          type: string
          x-order: '5'
    management.ColumnQueryTimeDecision:
      type: object
      properties:
        database_type:
          type: integer
          x-order: '0'
        database_name:
          type: string
          x-order: '1'
        schema_name:
          type: string
          x-order: '2'
        table_or_view_name:
          type: string
          x-order: '3'
        column_name:
          type: string
          x-order: '4'
        applied_policy:
          allOf:
          - $ref: '#/components/schemas/management.AppliedPolicy'
          x-order: '5'
        policy_info:
          type: array
          items:
            $ref: '#/components/schemas/management.PolicyInfo'
          x-order: '6'
    management.ColumnAuditTimeDecision:
      type: object
      properties:
        database_type:
          type: integer
          x-order: '0'
        database_name:
          type: string
          x-order: '1'
        schema_name:
          type: string
          x-order: '2'
        table_or_view_name:
          type: string
          x-order: '3'
        column_name:
          type: string
          x-order: '4'
        applied_policy:
          allOf:
          - $ref: '#/components/schemas/management.AppliedPolicy'
          x-order: '5'
        policy_info:
          type: array
          items:
            $ref: '#/components/schemas/management.PolicyInfo'
          x-order: '6'
    management.TagPolicy:
      type: object
      properties:
        query_time_decision:
          type: array
          items:
            $ref: '#/components/schemas/management.TagQueryTimeDecision'
          x-order: '0'
        audit_time_decision:
          type: array
          items:
            $ref: '#/components/schemas/management.TagAuditTimeDecision'
          x-order: '1'
    auditfilter.Dimension:
      type: string
      enum:
      - user
      - database
      - schema
      - table
      - column
      - statement_type
      - statement_text
      - event_name
      - time_of_day
      - query_status
      - repo_user
      - client_ip
      - client_app
      - client_port
      - repo_type
      - repo_host
      - sidecar_id
      - connection_authorized
      - authorization_type
      - oltp_row_count
      - bytes_returned
      - policy_applied
      - policy_type
      - user_email
      - user_group
      - snowflake_role
      - snowflake_roles
      - snowflake_warehouse
      - snowflake_warehouse_size
      - snowflake_ip_address
      - snowflake_client
      - snowflake_session_id
      - snowflake_query_tag
      - snowflake_row_count
      - snowflake_account
      - snowflake_account_region
      - snowflake_masking_policy
      - snowflake_column_policy
      - snowflake_execution_duration
      - snowflake_tag_name
      - snowflake_tag_value
      x-enum-varnames:
      - DimUser
      - DimDatabase
      - DimSchema
      - DimTable
      - DimColumn
      - DimStatementType
      - DimStatementText
      - DimEventName
      - DimTimeOfDay
      - DimQueryStatus
      - DimRepoUser
      - DimClientIP
      - DimClientApp
      - DimClientPort
      - DimRepoType
      - DimRepoHost
      - DimSidecarID
      - DimConnectionAuthorized
      - DimAuthorizationType
      - DimRowCount
      - DimBytesReturned
      - DimPolicyApplied
      - DimPolicyType
      - DimUserEmail
      - DimUserGroup
      - DimSnowflakeRole
      - DimSnowflakeRoles
      - DimSnowflakeWarehouse
      - DimSnowflakeWarehouseSize
      - DimSnowflakeIPAddress
      - DimSnowflakeClient
      - DimSnowflakeSessionID
      - DimSnowflakeQueryTag
      - DimSnowflakeRowCount
      - DimSnowflakeAccount
      - DimSnowflakeAccountRegion
      - DimSnowflakeMaskingPolicy
      - DimSnowflakeColumnPolicy
      - DimSnowflakeExecutionDuration
      - DimSnowflakeTagName
      - DimSnowflakeTagValue
    auditfilter.RangeValue:
      type: object
      required:
      - max
      - min
      properties:
        max:
          type: number
        min:
          type: number
    management.TagQueryTimeDecision:
      type: object
      properties:
        tag_name:
          type: string
          x-order: '0'
        tag_value:
          type: string
          x-order: '1'
        applied_policy:
          allOf:
          - $ref: '#/components/schemas/management.AppliedPolicy'
          x-order: '2'
        policy_info:
          type: array
          items:
            $ref: '#/components/schemas/management.PolicyInfo'
          x-order: '3'
    management.UserIdentity:
      type: object
      properties:
        type:
          type: string
          x-order: '0'
        database_id:
          type: string
          x-order: '1'
    management.Actor:
      type: object
      properties:
        username:
          type: string
          x-order: '0'
        current_role:
          type: string
          x-order: '1'
        roles:
          type: array
          items:
            type: string
          x-order: '2'
        client:
          type: string
          x-order: '3'
        ip_address:
          type: string
          x-order: '4'
    main.SearchRequestDoc:
      type: object
      properties:
        filter:
          $ref: '#/components/schemas/main.FilterNodeDoc'
        timezone:
          description: 'Timezone is the IANA zone for time_of_day comparisons (e.g.

            "America/New_York") — pass the dam rule''s timezone to replay its

            filter. Required when the filter contains a time_of_day dimension,

            forbidden otherwise.'
          type: string
    management.Result:
      type: object
      properties:
        row_count:
          type: integer
          x-order: '0'
        tag_policy:
          allOf:
          - $ref: '#/components/schemas/management.TagPolicy'
          x-order: '1'
        column_policy:
          allOf:
          - $ref: '#/components/schemas/management.ColumnPolicy'
          x-order: '2'
    management.PolicyInfo:
      type: object
      properties:
        id:
          type: integer
          x-order: '0'
        name:
          type: string
          x-order: '1'
        type:
          type: string
          x-order: '2'
        masking_type:
          type: string
          x-order: '3'
    auditfilter.Op:
      type: string
      enum:
      - and
      - or
      - eq
      - neq
      - in
      - contains
      - regex
      - cidr
      - gt
      - gte
      - lt
      - lte
      - range
      - between
      - exists
      - key_exists
      - key_eq
      x-enum-varnames:
      - OpAnd
      - OpOr
      - OpEq
      - OpNeq
      - OpIn
      - OpContains
      - OpRegex
      - OpCIDR
      - OpGt
      - OpGte
      - OpLt
      - OpLte
      - OpRange
      - OpBetween
      - OpExists
      - OpKeyExists
      - OpKeyEq
    management.ColumnPolicy:
      type: object
      properties:
        query_time_decision:
          type: array
          items:
            $ref: '#/components/schemas/management.ColumnQueryTimeDecision'
          x-order: '0'
        audit_time_decision:
          type: array
          items:
            $ref: '#/components/schemas/management.ColumnAuditTimeDecision'
          x-order: '1'
    management.TriggerSearchOutput:
      type: object
      properties:
        search_uuid:
          description: UUID of the search. Used to retrieve the results. Expires 30 days after creation.
          type: string
    management.Account:
      type: object
      properties:
        region:
          type: string
          x-order: '0'
        identifier:
          type: string
          x-order: '1'
    management.Query:
      type: object
      properties:
        id:
          type: string
          x-order: '0'
        start_time:
          type: string
          x-order: '1'
        start_time_epoch:
          type: integer
          x-order: '2'
        completed_time:
          type: string
          x-order: '3'
        completed_time_epoch:
          type: integer
          x-order: '4'
        text:
          type: string
          x-order: '5'
        warehouse:
          type: string
          x-order: '6'
        warehouse_size:
          type: string
          x-order: '7'
        session_id:
          type: string
          x-order: '8'
        type:
          type: string
          x-order: '9'
    auditfilter.BetweenValue:
      type: object
      required:
      - end
      - start
      properties:
        end:
          type: string
        start:
          type: string
    main.GetResultOutput:
      type: object
      properties:
        next_page_token:
          description: Token to retrieve the next page of results. If not present, there are no more results.
          type: string
          x-order: '0'
        query_audits:
          description: Query audits.
          type: array
          items:
            $ref: '#/components/schemas/management.QueryAudit'
          x-order: '1'
  securitySchemes:
    BasicAuth:
      type: http
      scheme: basic