Introducing SOC Optimization API

SOC optimization is a new feature designed to combine the power of out of the box content with the flexibility of the SIEM to help you optimize your SOC processes and coverage to your organization's specific needs, priorities, threats and environment. The first phase of this new feature helps you gain deep insights into your data usage patterns and coverage gaps against specific threats. It provides actionable recommendations to tighten your ingestion rates for data that doesn't provide security value, leverage correctly the data the does and improve your current coverage based on the threat landscape. You can learn more about the feature with the following resources.

Documentation: SOC optimization overview ; Recommendation's logic

Short overview and demo: SOC optimization Ninja show

In dept webinar: Manage your data, costs and protections with SOC optimization

In this blog, we will focus on the API usage for SOC optimization. That's right, if you didn't know, there is an API available for you to interact with programmatically.


Having an API for the SOC optimization feature is crucial for several reasons. We aim to unlock the power of precision-driven security and empower security teams through API with flexibility in , integration, customization, scalability and real-time access to SOC optimization data.

Refer to the Swagger specification and examples to learn more about the API.


Use cases

There are numerous scenarios where the SOC optimization API can be utilized. Here are some key use cases:

  • You can build custom reports and dashboards, for example, with Workbooks, , and other reporting tools. The Sentinel Optimization workbook has been updated with recommendation data via the API.
  • Integrate with third-party tools such as SOAR, ITSM, or any other applications that need to integrate with recommendations programmatically.
  • The API allows real-time access to SOC Optimization data. Security teams can retrieve up-to-date recommendations, trigger evaluations if needed, and respond promptly to the suggestions. Recommendations are calculated every 24 hours, and with the API you're always up to date.
  • For customers or MSSPs managing multiple environments, the API provides a scalable way to handle recommendations across multiple workspaces.
  • You can export the data from the API and store it externally for audit, archiving, or tracking trends.

“We consider this feature as a valuable source of data for us and the customers we protect, it speeds up many tasks for us and provides meaningful insights we can act upon. The API and the reporting that it enables improves our efficiency and accuracy and reduces manual effort for custom reporting, thus reducing our costs and providing a better fidelity of service. “
Clive Watson – Solution Director, Cyber

Available actions

Below is a summary of the API actions and sample their sample responses.

1. Get recommendations 


Use this action to list all the recommendations in your workspace.


GET /subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.OperationalInsights/workspaces/{workspaceName}/providers/Microsoft.SecurityInsights/recommendations



2. Get recommendation


This allows you to get a specific recommendation by id. The id can be obtained from the previous action.


GET /subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.OperationalInsights/workspaces/{workspaceName}/providers/Microsoft.SecurityInsights/recommendations/{recommendationId}




3. Patch recommendation


This allows you to update the status of a recommendation. For example, mark a recommendation as in progress, completed, dismissed or reactivate a recommendation.

Supported values when configuring the state property are ‘Active', ‘InProgress', ‘Dismissed', ‘CompletedByUser' and ‘CompletedBySystem'


PATCH /subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.OperationalInsights/workspaces/{workspaceName}/providers/Microsoft.SecurityInsights/recommendations/{recommendationId}



4. Reevaluate recommendation


Use this action to manually trigger the evaluation for a recommendation.


POST /subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.OperationalInsights/workspaces/{workspaceName}/providers/Microsoft.SecurityInsights/recommendations/{recommendationId} /triggerEvaluation




Sample workbook

If you need a sample for reference or to get started, you can refer to the Microsoft Sentinel Optimization Workbook as mentioned earlier. Install the workbook from the content hub, save the template, and launch the workbook. You will find the ‘SOC Optimization' tab that visualizes the data based on the SOC optimization API.


Expand the items under ‘Details' to drill down into each optimization type. Below are sample screenshots for ‘data value optimization' and ‘threat-based optimization' from the workbook.



Edit the workbook to check the parameters defined for SOC optimization (at the top of the workbook) and see how each visualization is built.


Customer story

Below is the case study shared by Cyber:

“When we first saw the preview of SOC Optimization the idea resonated with work we already do for customers as their MSSP. We knew that customers would be excited by this level of detail and insight provided and they would ask us questions about this. We were impressed with the API provided from day one, it worked immediately with Sentinel Workbooks, and we were able to almost immediately incorporate new reports on a customer-by-customer basis.   

However, we were really interested in how we could scale this knowledge and be proactive. This is where the API really helped us; we were able to use it to detect all customers with data and bring those insights centrally to report on them. This gave us a few advantages; one was that we could see where a customer had an issue and where we might need to assist. For example, a customer has a warning about zero usage of a table (which you can't detect otherwise), this helps our on-boarding team and improves our ongoing management, as it's good to know that a table may have been asked for but isn't used, or that over time the usage or importance of this may have changed and maybe we can adjust accordingly.  


Detection coverage is a key part of us being an MSSP, we look to provide threat-led analytic rules to our customers, so having insights from the API on what might be missing and areas to investigate is crucial and looking at that data across customers at scale has given us many invaluable insights. For example, one customer being recommended coverage is important but having many customers with the same recommendation might mean this is a crucial task and we need to adopt the recommendation faster.  

What we also appreciated was the link back to the Microsoft Sentinel GitHub for each analytic and the counts of active vs. available, so not only did we know that there were, for example, eight of 10 active detections deployed, but we had the GUID of that detection to look it up. With that data were able to correlate that GUID to our own GitHub repository to match to any customization we have done to that use case.”


Get started with the SOC optimization API today. We hope that this detailed walkthrough will help you unlock your use cases via the API.

Here is a list of useful resources mentioned in the blog:

API: Swagger specification and examples

Documentation: SOC optimization overview ; Recommendation's logic

Short overview and demo: SOC optimization Ninja show

In dept webinar: Manage your data, costs and protections with SOC optimization

Workbook: Sentinel Optimization workbook


This article was originally published by Microsoft's Sentinel Blog. You can find the original article here.