investigationSession resource type

Namespace: microsoft.graph

Important

APIs under the /beta version in Microsoft Graph are subject to change. Use of these APIs in production applications is not supported. To determine whether an API is available in v1.0, use the Version selector.

Represents an execution of a security playbook against typed inputs. Create a session to start asynchronous investigation work, and read its status and statusDetail to monitor progress. Inputs belong to the session, and outputs are session-owned stored files.

Inherits from entity.

Methods

Method	Return type	Description
List sessions	investigationSession collection	Get the caller's sessions.
Create	investigationSession	Start a playbook execution.
Get	investigationSession	Read the session and its status.
investigationSession: cancel	investigationSession	Request cancellation.
List inputs	investigationInput collection	Get the session inputs.
List outputs	investigationOutput collection	Get the session outputs.
List agentRuns	agentRun collection	Get the session's agent runs.
Get playbookDefinition	playbookDefinition	Read the selected definition.

Properties

Property	Type	Description
createdDateTime	DateTimeOffset	The UTC date and time when the resource was created, in ISO 8601 format. Read-only.
displayName	String	The session name generated by the service. Read-only.
id	String	The unique, read-only identifier of the resource.
initiatedBy	investigationIdentitySet	The initiating principals recorded by the service, when available. Read-only. This property doesn't select an execution identity.
lastModifiedDateTime	DateTimeOffset	The UTC date and time when the resource was last updated, in ISO 8601 format. Read-only.
status	longRunningOperationStatus	The service-computed processing status. The possible values are: notStarted, running, succeeded, failed, unknownFutureValue. A canceled execution has failed status and canceled statusDetail. A request for input has running status and waitingForInput statusDetail. Read-only. Supports $filter (eq, or, in) when listing sessions.
statusDetail	String	Additional processing detail, including waitingForInput or canceled, when the status alone doesn't describe the source lifecycle. Read-only. Doesn't support $filter. For the session lifecycle combinations, see Get agentic session.
tags	String collection	The service-generated tags for the session. Read-only. Can't be supplied when creating a session.

Relationships

Relationship	Type	Description
agentRuns	agentRun collection	The read-only agent runs owned by this session. Supports list and keyed GET with $select and server-driven paging.
inputs	investigationInput collection	The input references contained by the session. Required inline array on session creation; it can be empty if the playbook permits it. Each new input accepts only kind and value. After creation, supports only list and keyed GET with $select and server-driven paging.
outputs	investigationOutput collection	The read-only stored-file outputs owned by this session. Supports list and keyed GET with $select, server-driven paging, and authenticated content downloads.
playbookDefinition	playbookDefinition	The required reference to an existing catalog definition, selected once by playbookDefinition@odata.bind on creation. Supports GET with $select. Deep insert, rebinding, $ref writes, and $expand aren't supported.

JSON representation

The following JSON representation shows the resource type.

{
  "@odata.type": "#microsoft.graph.investigationSession",
  "id": "String (identifier)",
  "status": "String",
  "statusDetail": "String",
  "displayName": "String",
  "createdDateTime": "String (timestamp)",
  "lastModifiedDateTime": "String (timestamp)",
  "initiatedBy": {
    "@odata.type": "microsoft.graph.investigationIdentitySet"
  },
  "tags": [
    "String"
  ]
}