Batch queries
The Azure Monitor Log Analytics API supports batching queries together. Batch queries currently require Microsoft Entra authentication.
Request format
To batch queries, use the API endpoint, adding $batch at the end of the URL: https://api.loganalytics.azure.cn/v1/$batch.
If no method is included, batching defaults to the GET method. On GET requests, the API ignores the body parameter of the request object.
The batch request includes regular headers for other operations:
Content-Type: application/json
Authorization: Bearer <user token>
The body of the request is an array of objects containing the following properties:
idheadersbodymethodpathworkspace
Example:
POST https://api.loganalytics.azure.cn/v1/$batch
Content-Type: application/json
Authorization: Bearer <user token>
Cache-Control: no-cache
{
"requests":
[
{
"id": "1",
"headers": {
"Content-Type": "application/json"
},
"body": {
"query": "AzureActivity | summarize count()",
"timespan": "PT1H"
},
"method": "POST",
"path": "/query",
"workspace": "workspace-1"
},
{
"id": "2",
"headers": {
"Content-Type": "application/json"
},
"body": {
"query": "ApplicationInsights | limit 10",
"timespan": "PT1H"
},
"method": "POST",
"path": "/fakePath",
"workspace": "workspace-2"
}
]
}
Response format
The response format is a similar array of objects. Each object contains:
- The ID
- The HTTP status code of the particular query
- The body of the returned response for that query.
If a query doesn't return successfully, the response body contains error messages. The error messages only apply to the individual queries in the batch; the batch itself returns a status code independent of the return values of its members. The batch returns successfully if the batch is:
- Well-formed and properly formatted
- Authenticated
- Authorized
The batch returns successfully even when the results of its member queries may be a mix of successes and failures.
Example:
{
"responses":
[
{
"id": "2",
"status": 404,
"body": {
"error": {
"message": "The requested path does not exist",
"code": "PathNotFoundError"
}
}
},
{
"id": "1",
"status": 200,
"body": {
"tables": [
{
"name": "PrimaryResult",
"columns": [
{
"name": "Count",
"type": "long"
}
],
"rows": [
[
7240
]
]
}
]
}
}
]
}
Behavior and errors
The order of responses inside the returned object isn't related to the order in the request. The time it takes determines each individual query to complete. Use IDs to map the query response objects to the original requests. Don't assume that the query responses are in order.
An entire batch request only fails if:
- The JSON format of the outer payload isn't valid.
- Authentication fails: The user doesn't provide an authentication token, or the token is invalid.
- Individual request objects in the batch don't have the required properties, or there are duplicate IDs.
Under these conditions, the shape of the response is different from the normal container. The objects contained within the batch object may each fail or succeed independently, see the following example errors.
Example errors
This list is a nonexhaustive list of examples of possible errors and their meanings.
400 - Malformed request. The outer request object wasn't valid JSON.
{ "error": { "message": "The request had some invalid properties", "code": "BadArgumentError", "innererror": { "code": "QueryValidationError", "message": "Failed parsing the query", "details": [ { "code": "InvalidJsonBody", "message": "Unexpected end of JSON input", "target": null } ] } } }403 - Forbidden. The token provided doesn't have access to the resource you're trying to access. Make sure that your token request has the correct resource, and you've granted permissions for your Microsoft Entra application.
{ "error": { "message": "The provided authentication is not valid for this resource", "code": "InvalidTokenError", "innererror": { "code": "SignatureVerificationFailed", "message": "Could not validate the request" } } }204 - Not Placed. You have no data for the API to pull in the backing store. As a 2xx error, this is technically a successful request. However, in a batch, it's useful to note the error.
{ "responses": [ { "id": "2", "status": 204, "body": { "error": { "code": "WorkspaceNotPlacedError" } } } ] }404 - Not found. The query path does not exist. This error can also occur in a batch if you specify an invalid HTTP method in the individual request.
{ "responses": [ { "id": "1", "status": 404, "body": { "error": { "message": "The requested path does not exist", "code": "PathNotFoundError" } } } ] }400 - Failed to resolve resource. The GUID representing the workspace is incorrect.
{ "responses": [ { "id": "1", "status": 400, "body": { "error": { "code": "FailedToResolveResource", "message": "Resource identity could not be resovled" } } } ] }