Skip to content

client.advanced_queries

Execute Defender advanced hunting queries.

Property

client.advanced_queries

Methods

  • run(query: str) -> AdvancedHuntingQueriesResults: run a KQL-style advanced hunting query and return a lazy wrapper.

Return behavior

AdvancedHuntingQueriesResults exposes the same terminal methods used by the shared results wrappers:

  • to_dicts()
  • to_json()
  • to_arrow()
  • to_polars()
  • refresh()

Notes

  • The output schema depends on the query you run.
  • The result wrapper caches materialized data until refresh() is called.

API

Advanced Hunting Queries endpoint for the Defender for Endpoint API.

Provides AdvancedHuntingQueriesEndpoint.run(query) for executing KQL queries against /api/advancedqueries/run and an AdvancedHuntingQueriesResults wrapper that materialises rows to dicts, JSON, PyArrow tables, or Polars DataFrames on demand.

AdvancedHuntingQueriesResults 

AdvancedHuntingQueriesResults(
    endpoint: AdvancedHuntingQueriesEndpoint,
    path: str,
    query: str,
)

Results from the /api/advancedqueries/run endpoint.

to_dicts 

to_dicts() -> list[dict]

Materialize results into a list of dicts.

to_json 

to_json(indent: bool = False) -> str | bytes

Materialize results into a JSON string.

Returns a str if indent=False, bytes if indent=True (since orjson returns bytes). You can decode the bytes to get a str if needed.

to_arrow 

to_arrow() -> Table

Materialize results into a PyArrow Table.

to_polars 

to_polars() -> DataFrame

Materialize results into a Polars DataFrame.

refresh 

refresh() -> AdvancedHuntingQueriesResults

Clear any cached results, forcing the next materialization to re-query the API.

AdvancedHuntingQueriesEndpoint 

AdvancedHuntingQueriesEndpoint(
    http: Client, auth: MSALAuth
)

Endpoint for /api/advancedqueries/run.

run 

run(query: str) -> AdvancedHuntingQueriesResults

Run an advanced hunting query.

Docs: https://learn.microsoft.com/en-us/defender-endpoint/api/run-advanced-query-api