Azure Log Analytics API

Leverage the power of Azure Log Analytics to programmatically query and manage your logs.

Introduction to Log Analytics API

The Azure Log Analytics API provides a rich set of RESTful endpoints that allow you to interact with your log data. You can use these APIs to:

  • Query logs using the powerful Kusto Query Language (KQL).
  • Retrieve metadata about your workspace and tables.
  • Manage data ingestion and retention policies.
  • Automate monitoring and reporting tasks.

This documentation outlines the key API operations, authentication methods, and best practices for integrating with Log Analytics.

Authentication

Access to the Log Analytics API requires authentication. The recommended method is using Azure Active Directory (Azure AD) service principals or managed identities. Ensure your application has the necessary permissions (e.g., 'Log Analytics Reader' role) to perform the desired operations.

Using Azure AD

Obtain an OAuth 2.0 access token from Azure AD and include it in the Authorization header of your API requests as a Bearer token.

Authorization: Bearer <YOUR_ACCESS_TOKEN>

Querying Logs

The primary operation for retrieving log data is the Query API. This API allows you to submit Kusto Query Language (KQL) statements to your Log Analytics workspace.

Endpoint

POST https://api.loganalytics.io/v1/workspaces/{workspaceId}/query

Request Body

The request body is a JSON object containing the KQL query and optional parameters.


{
  "query": "Perf | take 10",
  "timespan": "PT1H",
  "visualizations": ["table"]
}

Request Parameters

Parameter Type Description Required
query string The Kusto Query Language (KQL) statement to execute. Yes
timespan string The time range for the query, e.g., "PT1H" (1 hour), "P7D" (7 days). No
top integer Maximum number of results to return. No
skip integer Number of results to skip. No
client_request_id string A unique identifier for the client request. No
timeout integer Query timeout in seconds. No
include_statistics boolean If true, returns query execution statistics. No
visualizations array of strings Specifies the desired visualization format (e.g., "table", "chart"). No

Example Request (curl)


curl 'https://api.loganalytics.io/v1/workspaces/{workspaceId}/query' \
  -X POST \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -d '{
        "query": "AzureActivity | where ResourceProvider == \"MICROSOFT.COMPUTE\" | take 5",
        "timespan": "PT5M"
      }'

Response Body (Success)

The response contains query results, potentially including tables, statistics, and visualizations.


{
  "tables": [
    {
      "name": "PrimaryResult",
      "columns": [
        {"name": "TimeGenerated", "type": "datetime"},
        {"name": "OperationName", "type": "string"},
        {"name": "ResourceProvider", "type": "string"}
      ],
      "rows": [
        ["2023-10-27T10:00:00Z", "StartVirtualMachine", "MICROSOFT.COMPUTE"],
        ["2023-10-27T10:05:00Z", "StopVirtualMachine", "MICROSOFT.COMPUTE"]
      ]
    }
  ],
  "stats": {
    "query_records_scanned": 15000,
    "query_execution_time": 0.123
  }
}

Workspace and Table Metadata

Retrieve information about your Log Analytics workspaces and the tables within them.

List Workspaces

GET https://management.azure.com/subscriptions/{subscriptionId}/providers/Microsoft.OperationalInsights/workspaces?api-version=2020-08-01

List Tables in a Workspace

GET https://api.loganalytics.io/v1/workspaces/{workspaceId}/tables

Get Table Schema

GET https://api.loganalytics.io/v1/workspaces/{workspaceId}/tables/{tableName}/schema

Best Practices

  • Optimize Queries: Write efficient KQL queries to minimize execution time and cost. Use take and where clauses judiciously.
  • Handle Pagination: For large result sets, implement pagination using top and skip parameters.
  • Error Handling: Implement robust error handling to manage API rate limits, authentication failures, and query errors.
  • Asynchronous Operations: For long-running queries, consider using asynchronous patterns if supported by your SDK or client library.
  • Security: Securely manage your Azure AD credentials and grant only necessary permissions.
Explore SDKs and Tools