Edit

security: getHuntingSchema

Namespace: microsoft.graph.security

Important

APIs under the /beta version in Microsoft Graph are subject to change. Use of these APIs in production applications is not supported. To determine whether an API is available in v1.0, use the Version selector.

Retrieve the advanced hunting schema accessible to the signed-in user, including the tables and functions the user is authorized to query and invoke in advanced hunting with Microsoft Defender XDR.

The returned schema reflects the user's effective permissions. Each user within a tenant may have a different effective schema depending on their role and access level.

Common use cases include:

  • Preventing unauthorized queries: Determine which tables and functions a user can access before executing Kusto queries, reducing the risk of authorization failures.
  • Permission-aware query generation: Enable applications and tools to construct queries dynamically based on the user's effective schema.

Permissions

Choose the permission or permissions marked as least privileged for this API. Use a higher privileged permission or permissions only if your app requires it. For details about delegated and application permissions, see Permission types. To learn more about these permissions, see the permissions reference.

Permission type Least privileged permission Higher privileged permissions
Delegated (work or school account) Not supported. Not supported.
Delegated (personal Microsoft account) Not supported. Not supported.
Application Not supported. Not supported.

Important

The signed-in user must also be assigned a Microsoft Defender XDR Unified RBAC role that grants permission to run advanced hunting queries, or one of the following Microsoft Entra ID roles which provide only the least privilege necessary: Security Reader, Security Operator, Security Administrator.

HTTP request

GET /security/getHuntingSchema

Function parameters

This method doesn't support any OData query parameters to customize the response.

Request headers

Name Description
Authorization Bearer {token}. Required. Learn more about authentication and authorization.

Request body

Don't supply a request body for this method.

Response

If successful, this function returns a 200 OK response code and a huntingSchemaResult in the response body.

Examples

Request

GET https://graph.microsoft.com/beta/security/getHuntingSchema

Response

HTTP/1.1 200 OK
Content-type: application/json

{
  "tables": [
    {
      "name": "DeviceProcessEvents",
      "description": "Process creation and related events",
      "columns": [
        {
          "name": "Timestamp",
          "dataType": "DateTime",
          "description": "Date and time when the record was generated"
        },
        {
          "name": "DeviceId",
          "dataType": "String",
          "description": "Unique identifier for the device in the service"
        },
        {
          "name": "DeviceName",
          "dataType": "String",
          "description": "Fully qualified domain name (FQDN) of the device"
        }
      ]
    },
    {
      "name": "DeviceNetworkEvents",
      "description": "Network connection and related events",
      "columns": [
        {
          "name": "Timestamp",
          "dataType": "DateTime",
          "description": "Date and time when the record was generated"
        },
        {
          "name": "DeviceId",
          "dataType": "String",
          "description": "Unique identifier for the device in the service"
        }
      ]
    }
  ],
  "functions": {
    "builtInFunctions": [
      {
        "huntingFunctionId": 1,
        "name": "FileProfile",
        "path": "Built-in",
        "documentation": "Enriches query results with file information such as file name, size, and hash.",
        "inputParameters": [
          {
            "name": "SHA1",
            "cslType": "string",
            "defaultValue": null
          }
        ],
        "outputColumns": [
          {
            "name": "SHA1",
            "dataType": "String",
            "description": "SHA-1 hash of the file"
          },
          {
            "name": "SHA256",
            "dataType": "String",
            "description": "SHA-256 hash of the file"
          }
        ]
      }
    ],
    "savedFunctions": [
      {
        "huntingFunctionId": 100,
        "name": "MyCustomQuery",
        "path": "Shared",
        "description": "A custom query that filters device events by severity.",
        "createdBy": "user@contoso.com",
        "lastModifiedBy": "user@contoso.com",
        "lastModifiedDateTime": "2026-04-15T10:30:00Z",
        "inputParameters": [],
        "outputColumns": [
          {
            "name": "DeviceId",
            "dataType": "String",
            "description": "Unique identifier for the device"
          }
        ]
      }
    ]
  }
}
  • Last updated on