Query/management HTTP request

Request verb and resource

For example, to send a management command (“management”) to a service endpoint, use the following request line:

POST https://help.kusto.windows.net/v1/rest/mgmt HTTP/1.1

See Request headers and Body to learn what to include. See Request headers and Body to learn what to include.

Request headers

The following table contains the common headers used for query and management operations.

The following table contains the common custom headers used for query and management operations. Unless noted, these headers are used only for telemetry purposes and don’t affect functionality.

All headers are optional. However, We recommend specifying the x-ms-client-request-id custom header. In some scenarios, such as canceling a running query, x-ms-client-request-id is required since it’s used to identify the request.

Request parameters

The following parameters can be passed in the request. They’re encoded in the request as query parameters or as part of the body, depending on whether GET or POST is used.

GET query parameters

When a GET request is used, the query parameters specify the request parameters.

Body

When a POST request is used, the body of the request contains a single UTF-8 encoded JSON document, which includes the values of the request parameters.

Examples

The following example shows the HTTP POST request for a query.

POST https://help.kusto.windows.net/v2/rest/query HTTP/1.1

Request headers

Accept: application/json
Authorization: Bearer ...AzureActiveDirectoryAccessToken...
Accept-Encoding: deflate
Content-Type: application/json; charset=utf-8
Host: help.kusto.windows.net
x-ms-client-request-id: MyApp.Query;e9f884e4-90f0-404a-8e8b-01d883023bf1
x-ms-user-id: EARTH\davidbg
x-ms-app: MyApp

Request body

{
  "db":"Samples",
  "csl":"print Test=\"Hello, World!\"",
  "properties":"{\"Options\":{\"queryconsistency\":\"strongconsistency\"},\"Parameters\":{},\"ClientRequestId\":\"MyApp.Query;e9f884e4-90f0-404a-8e8b-01d883023bf1\"}"
}

The following example shows how to create a request that sends the previous query, using curl. The following example shows how to create a request that sends the previous query, using curl.

1. Obtain a token for authentication.

   Replace AAD_TENANT_NAME_OR_ID, AAD_APPLICATION_ID, and AAD_APPLICATION_KEY with the relevant values, after setting up Microsoft Entra application authentication. Replace AAD_TENANT_NAME_OR_ID, AAD_APPLICATION_ID, and AAD_APPLICATION_KEY with the relevant values, after setting up Microsoft Entra application authentication.

   curl "https://login.microsoftonline.com/AAD_TENANT_NAME_OR_ID/oauth2/token" \
     -F "grant_type=client_credentials" \
     -F "resource=https://help.kusto.windows.net" \
     -F "client_id=AAD_APPLICATION_ID" \
     -F "client_secret=AAD_APPLICATION_KEY"
   

   This code snippet provides you with the bearer token.

   {
     "token_type": "Bearer",
     "expires_in": "3599",
     "ext_expires_in":"3599", 
     "expires_on":"1578439805",
     "not_before":"1578435905",
     "resource":"https://help.kusto.windows.net",
     "access_token":"eyJ0...uXOQ"
   }
   

2. Use the bearer token in your request to the query endpoint.

   curl -d '{"db":"Samples","csl":"print Test=\"Hello, World!\"","properties":"{\"Options\":{\"queryconsistency\":\"strongconsistency\"}}"}"' \
   -H "Accept: application/json" \
   -H "Authorization: Bearer eyJ0...uXOQ" \
   -H "Content-Type: application/json; charset=utf-8" \
   -H "Host: help.kusto.windows.net" \
   -H "x-ms-client-request-id: MyApp.Query;e9f884e4-90f0-404a-8e8b-01d883023bf1" \
   -H "x-ms-user-id: EARTH\davidbg" \
   -H "x-ms-app: MyApp" \
   -X POST https://help.kusto.windows.net/v2/rest/query
   

3. Read the response according to the response status codes.

4. Read the response according to the response status codes.

Set client request properties and query parameters

In the following request body example, the query in the csl field declares two parameters named n and d. The values for those query parameters are specified within the Parameters field under the properties field in the request body. The Options field defines client request properties. In the following request body example, the query in the csl field declares two parameters named n and d. The values for those query parameters are specified within the Parameters field under the properties field in the request body. The Options field defines client request properties.

{
    "db": "Samples",
    "csl": "declare query_parameters (n:long, d:dynamic); StormEvents | where State in (d) | top n by StartTime asc",
    "properties": {
        "Options": {
            "maxmemoryconsumptionperiterator": 68719476736,
            "max_memory_consumption_per_query_per_node": 68719476736,
            "servertimeout": "50m"
        },
        "Parameters": {
            "n": 10, "d": "dynamic([\"ATLANTIC SOUTH\"])"
        }
    }
}

For more information, see Supported request properties. For more information, see Supported request properties.

Send show database caching policy command

The following example sends a request to show the Samples database caching policy.

{
    "db": "Samples",
    "csl": ".show database Samples policy caching",
    "properties": {
        "Options": {
            "maxmemoryconsumptionperiterator": 68719476736,
            "max_memory_consumption_per_query_per_node": 68719476736,
            "servertimeout": "50m"
        }
    }
}