Skip to main content
The v2 API is REST + JSON over HTTPS. Every request authenticates with a service account using HTTP Basic, every response is wrapped in a standard envelope, and every error is RFC 7807 ProblemDetails. Base URL
Authentication
Conventions
  • Content-Type: application/json (or multipart/form-data for operating procedure uploads)
  • Property names are camelCase; enum values are PascalCase (Sentinel, High, TwentyFourHours)
  • Workspace IDs and most other identifiers are GUIDs
  • Source segment values: Sentinel, DefenderXDR, CrowdStrike, QRadar, Splunk, SentinelOne, SumoLogic. The segment is case-insensitive, so the lowercased source from a webhook event can be used as is. Any other value returns 400 VALIDATION_ERROR with the accepted values listed under errors.source.

Workspace-Scoped Endpoints

Path prefix: /workspaces/{workspaceId}/... The workspace ID is a GUID and identifies the customer environment the request operates against. The credential’s service account must have a role on the target workspace, otherwise the request returns 403 INSUFFICIENT_WORKSPACE_ROLE.
Every incident is the child of one SIEM source — the source is encoded as a route segment, not a query parameter.
Separate endpoints for the incident summary, entities, alert rules, bulk updates and the high-severity list are not on the v2 surface yet. They will be added once their handlers operate against an explicit source rather than implicitly defaulting to Sentinel. An incident’s entities are already returned in investigationDetails.entities by GET /workspaces/{workspaceId}/incidents/{source}/{incidentId}.

Cross-Workspace Endpoints

These endpoints span every workspace your service account can see — no workspace ID in the path. The handlers filter results to the workspaces the credential has been mapped to.

Paginating /incidents/across-workspaces

The cross-workspace incidents list uses opaque continuation tokens. The first request leaves the token map empty; every subsequent request echoes the previous response’s tokens back unchanged. Tokens are server-encrypted strings — treat them as a single blob the API gave you, never parse or construct one yourself. First request:
Response (truncated):
Next-page request — set isFirstCall: false and pass sourcePageTokens back verbatim as workspacePageTokens:
Iterate until the response returns moreIncidentsAvailable: false. A workspace that has finished paging drops out of sourcePageTokens on subsequent responses; do not synthesize entries for it. Page size is server-controlled. A token that has been modified or hand-built returns 400 VALIDATION_ERROR with the message One or more pagination tokens are invalid. Use the tokens from the previous response unmodified. Recover by restarting from the first call with an empty workspacePageTokens array.

Syncing incident updates with filterByLastModified

By default timeFilterSelection bounds the incident’s creation time, so a list call cannot tell you which existing incidents changed. If you mirror incidents into an external system and need to pick up updates, set filterByLastModified: true. The same window then bounds the incident’s last-modified time as recorded by the vendor (Microsoft Sentinel lastModifiedTimeUtc, Microsoft Defender XDR lastUpdateDateTime), and the page is ordered by last-modified time descending. Sentinel and Defender XDR move that timestamp on every change recorded on the incident: an alert grouped in, a severity change, a status change, an owner change, a label, or a comment. Incidents created long before the window are returned as soon as they are touched. Note that the two modes are not equivalent for a bounded window: an incident created inside the window but modified after its end matches the creation-time query and not the last-modified one. In a polling loop whose windows end at the time of each call, that incident simply shows up in the next poll. Polling pattern:
Poll on a fixed cadence, set customStartUtc to your previous customEndUtc minus a short overlap (one or two minutes), page until moreIncidentsAvailable is false, then fetch by id only the incidents whose lastModificationTime differs from the copy you stored. An unchanged incident returned twice because of the overlap compares equal and costs nothing. Things to know:
  • The filter uses the vendor’s last-modified time, not lastActivityTime. lastActivityTime is the event time of the latest alert and is usually earlier than the incident’s creation time; it does not move when an analyst edits the incident.
  • The response carries the incident as it is now, not the fields that changed. Keep comparing against your stored copy.
  • Supported for Sentinel and DefenderXDR. Leave sources empty to query both; naming any other source together with filterByLastModified returns 400 VALIDATION_ERROR (FilterByLastModified is supported for Sentinel, DefenderXDR only; …).
  • Changes that exist only inside ContraForce and are not written to the vendor incident do not move the vendor timestamp.
  • In this mode each workspace’s window is returned in full in one call unless it exceeds the server’s page cap (several hundred incidents per workspace). If moreIncidentsAvailable comes back true, narrow the window and call again rather than paging: vendor continuations are positional, and an incident edited past the window’s end between two calls can shift them. A short polling window never hits the cap.
  • Each page is ordered by last-modified time descending. Sources are merged per page, so if you do page, read every page before assuming you have the full window.

Reporting

The reporting endpoints return the totals, trends and records behind the portal’s reporting page, so you can feed them into your own dashboards and BI tools. They span workspaces, like the other cross-workspace endpoints.
  • Scope: incidents:read. A credential without it gets 403 INSUFFICIENT_SCOPE.
  • Workspaces: a service account reads the workspaces it holds a role on. Leave workspaceIds out to read all of them, or name up to 500. Naming a workspace the service account holds no role on returns 403 FORBIDDEN, the same answer as for an ID that does not exist.
  • Spend: a service account gets the activity counts but not the spend. costUsd, unitPriceUsd and totalTokens are null, costBasis is Restricted, and an investigation export has no cost column.

The selection

Every reporting call is a POST with the selection in the body, because a selection can hold more workspace IDs than fit in a URL:
  • from and to are UTC days, both included. A range spans at most 366 days.
  • Reports with a trend return one point per day for a range of up to 92 days, and one point per month for a longer range. granularity says which (day or month), and each point’s date is yyyy-MM-dd or yyyy-MM.
  • Breakdowns are objects keyed by name in the casing shown on the object models page, such as { "Agent": 71, "Analyst": 52 }.
  • Every report carries a read object describing how it was read (scope, workspaceCount, documentsRead, fromCache, authorizeMs, readMs). It is there for diagnosis; for a service account scope is always workspaces.

Ranking workspaces

/reporting/by-workspace takes the selection plus:
  • metric: received, closed, investigated, actions, breached or atRisk.
  • top: how many workspaces to list, from 1 to 10. The default is 6.
It returns the workspaces with the highest value, highest first, and none with a value of zero. remainder is the total less the listed workspaces, so the breakdown adds up to total, and otherWorkspaces counts the selected workspaces that are not listed.

Reading the records

/reporting/facts returns the records behind a report, one record type at a time. Send the selection, a type, any filters that apply to it, and optionally pageSize (1 to 200, default 50):
  • severity is Informational, Low, Medium or High.
  • rule is an incident title, exactly as closedByRule lists it in the incident-flow report. Other, the remainder in that report, is not a rule and returns 400 VALIDATION_ERROR.
  • A filter that does not apply to the type returns 400 VALIDATION_ERROR.
  • verdict, slaType and tier are matched in any case. Any other value returns 400 VALIDATION_ERROR, and its detail lists the accepted values.
  • closerType, outcome and severity must be written exactly as listed, including case. Any other value is not refused: it matches no records.
Every record carries id, type, workspaceId, day, eventAt and the incident it is about (source, id, number, severity, title), plus the fields of its own type. The fields of other types are null. Paging: a response with a continuationToken has more records. Send the same body again with that token in its continuationToken field to read the next page, until the token comes back null. A page can hold fewer than pageSize records while a token remains. A token belongs to the body it came from: changing the selection or the filters while paging returns 400 VALIDATION_ERROR.

Exporting the records

/reporting/facts/export takes the same body as /reporting/facts, without the paging fields, and returns every matching record as one table:
  • columns: each column’s header and kind (text, number or time).
  • rows: one array of cells per record, in column order. Every cell is a string, or null when the record has no value for it. Times are UTC ISO 8601 and numbers use a period as the decimal separator.
An export holds at most 50,000 rows. A selection with more returns 400 VALIDATION_ERROR; narrow the dates or the filters and try again.

Rate limits

Each service account can make 120 reporting calls a minute, and separately 10 exports a minute. All of a service account’s credentials share these budgets. A call over the limit returns 429 Too Many Requests with an empty body and no Retry-After header. The budget refills at the end of each one-minute window: wait, then retry. Pace bulk pulls to stay under the limit rather than retrying in a tight loop.

Organization-Scoped Endpoints

These endpoints operate on the organization (service provider). The credential’s service account must hold the relevant org-level scope; workspace mappings are not required.
Read (webhooks:read):Manage (webhooks:manage):

What Comes Back

Every successful response is wrapped in the standard envelope:
List endpoints add a pagination block; see the object models page for shapes per endpoint family. Error responses are RFC 7807 ProblemDetails (application/problem+json) with a stable code extension you can switch on — the error reference lists every code.
Last modified on November 9, 2026