Livy Sessions - List Livy Sessions

Service:: Notebook

API Version:: v1

Returns a list of livy sessions from the specified item identifier.
This API supports pagination.

Permissions

The caller must have read permissions for the notebook.

Required Delegated Scopes

Notebook.Read.All or Notebook.ReadWrite.All or Item.Read.All or Item.ReadWrite.All

Microsoft Entra supported identities

This API supports the Microsoft identities listed in this section.

Identity	Support
User	Yes
Service principal and Managed identities	Yes

Interface

GET https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/notebooks/{notebookId}/livySessions

With optional parameters:

GET https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/notebooks/{notebookId}/livySessions?continuationToken={continuationToken}

URI Parameters

Name	In	Required	Type	Description
notebookId	path	True	string (uuid)	The notebook ID.
workspaceId	path	True	string (uuid)	The workspace identifier.
continuationToken	query		string	Token to retrieve the next page of results, if available.

Responses

Name Type Description

200 OK

Name	Type	Description
200 OK	LivySessions	OK -- Returns a list of all livy sessions associated to an itemId.
429 Too Many Requests	ErrorResponse	The service rate limit was exceeded. The server returns a `Retry-After` header indicating, in seconds, how long the client must wait before sending additional requests. Headers Retry-After: integer
Other Status Codes	ErrorResponse	Common error codes: SparkCoreItemNotFound - Notebook identifier does not exist SparkCoreUnexpectedException - Unhandled exception ocurred.

LivySessions

OK -- Returns a list of all livy sessions associated to an itemId.

429 Too Many Requests

ErrorResponse

The service rate limit was exceeded. The server returns a Retry-After header indicating, in seconds, how long the client must wait before sending additional requests.

Headers

Retry-After: integer

Other Status Codes

ErrorResponse

Common error codes:

SparkCoreItemNotFound - Notebook identifier does not exist
SparkCoreUnexpectedException - Unhandled exception ocurred.

Examples

List all livy sessions example

Sample request

HTTP

GET https://api.fabric.microsoft.com/v1/workspaces/f8113ba8-dd81-443e-811a-b385340f3f05/notebooks/8cee7699-2e81-4121-9a53-cc9025046193/livySessions

Sample response

Status code:: 200

{
  "continuationToken": null,
  "continuationUri": null,
  "value": [
    {
      "sparkApplicationId": "application_1730933685452_0001",
      "state": "Cancelled",
      "livyId": "9611f500-bf44-42e0-a0de-78dacb374398",
      "origin": "SubmittedJob",
      "attemptNumber": 1,
      "maxNumberOfAttempts": 1,
      "livyName": "random_test_name_app",
      "submitter": {
        "id": "6f23a8a6-d954-4550-b91a-4df73ccd0311",
        "type": "User"
      },
      "item": {
        "workspaceId": "f8113ba8-dd81-443e-811a-b385340f3f05",
        "itemId": "8cee7699-2e81-4121-9a53-cc9025046193",
        "referenceType": "ById"
      },
      "itemName": "lh_itemName",
      "itemType": "Notebook",
      "jobType": "SparkBatch",
      "submittedDateTime": "2025-01-31T15:32:03Z",
      "startDateTime": "2025-01-31T15:34:11Z",
      "endDateTime": "2025-01-31T15:37:30Z",
      "queuedDuration": {
        "value": 1,
        "timeUnit": "Seconds"
      },
      "runningDuration": {
        "value": 180,
        "timeUnit": "Seconds"
      },
      "totalDuration": {
        "value": 360,
        "timeUnit": "Seconds"
      },
      "jobInstanceId": "c2baabbd-5327-430c-87a6-ff4f98285601",
      "creatorItem": {
        "workspaceId": "f8113ba8-dd81-443e-811a-b385340f3f05",
        "itemId": "8cee7699-2e81-4121-9a53-cc9025046193",
        "referenceType": "ById"
      },
      "cancellationReason": "User cancelled the Spark batch",
      "capacityId": "3c0cd366-dc28-4b6d-a525-4d415a8666e7",
      "operationName": "Batch Livy Run",
      "runtimeVersion": "1.3",
      "livySessionItemResourceUri": "",
      "driverMemory": 4,
      "driverCores": 2,
      "executorMemory": 8,
      "executorCores": 4,
      "numExecutors": 10,
      "isDynamicAllocationEnabled": true,
      "dynamicAllocationMaxExecutors": 20
    }
  ]
}

Definitions

Name	Description
Duration	A duration.
EntireTenantPrincipal	Represents a tenant principal
ErrorRelatedResource	The error related resource details object.
ErrorResponse	The error response.
ErrorResponseDetails	The error response details.
GroupDetails	Group specific details. Applicable when the principal type is `Group`.
GroupPrincipal	Represents a security group.
GroupType	The type of the group. Additional group types may be added over time.
ItemReferenceById	An item reference by ID object.
ItemReferenceType	The item reference type. Additional `ItemReferenceType` types may be added over time.
JobType	Current state of the job.
LivySession	The livy session response
LivySessionItemType	The item type. Values are: `Lakehouse`, `SparkJobDefinition`, `Notebook`. Additional `LivySessionItemType` types may be added over time.
LivySessions	A paginated list of livy sessions.
Origin	Origin of the job.
PrincipalType	The type of the principal. Additional principal types may be added over time.
ServicePrincipalDetails	Service principal specific details. Applicable when the principal type is `ServicePrincipal`.
ServicePrincipalPrincipal	Represents a Microsoft Entra service principal.
ServicePrincipalProfileDetails	Service principal profile details. Applicable when the principal type is `ServicePrincipalProfile`.
ServicePrincipalProfilePrincipal	Represents a service principal profile.
State	Current state of the job.
TimeUnit	The unit of time for the duration. Additional duration types may be added over time.
UserDetails	User principal specific details. Applicable when the principal type is `User`.
UserPrincipal	Represents a Microsoft Entra user principal.

Duration

Object

A duration.

Name	Type	Description
timeUnit	TimeUnit	The unit of time for the duration. Additional duration types may be added over time.
value	number	The number of timeUnits in the duration.

EntireTenantPrincipal

Object

Represents a tenant principal

Name	Type	Description
displayName	string	The principal's display name.
id	string (uuid)	The principal's ID.
type	string: EntireTenant	The type of the principal. Additional principal types may be added over time.

ErrorRelatedResource

Object

The error related resource details object.

Name	Type	Description
resourceId	string	The resource ID that's involved in the error.
resourceType	string	The type of the resource that's involved in the error.

ErrorResponse

Object

The error response.

Name	Type	Description
errorCode	string	A specific identifier that provides information about an error condition, allowing for standardized communication between our service and its users.
message	string	A human readable representation of the error.
moreDetails	ErrorResponseDetails[]	List of additional error details.
relatedResource	ErrorRelatedResource	The error related resource details.
requestId	string (uuid)	ID of the request associated with the error.

ErrorResponseDetails

Object

The error response details.

Name	Type	Description
errorCode	string	A specific identifier that provides information about an error condition, allowing for standardized communication between our service and its users.
message	string	A human readable representation of the error.
relatedResource	ErrorRelatedResource	The error related resource details.

GroupDetails

Object

Group specific details. Applicable when the principal type is Group.

Name	Type	Description
groupType	GroupType	The type of the group. Additional group types may be added over time.

GroupPrincipal

Object

Represents a security group.

Name	Type	Description
displayName	string	The principal's display name.
groupDetails	GroupDetails	Group specific details. Applicable when the principal type is `Group`.
id	string (uuid)	The principal's ID.
type	string: Group	The type of the principal. Additional principal types may be added over time.

GroupType

Enumeration

The type of the group. Additional group types may be added over time.

Value	Description
Unknown	Principal group type is unknown.
SecurityGroup	Principal is a security group.
DistributionList	Principal is a distribution list.

ItemReferenceById

Object

An item reference by ID object.

Name	Type	Description
itemId	string (uuid)	The ID of the item.
referenceType	string: ById	The item reference type.
workspaceId	string (uuid)	The workspace ID of the item.

ItemReferenceType

Enumeration

The item reference type. Additional ItemReferenceType types may be added over time.

Value	Description
ById	The item is referenced by its ID.
ByVariable	The item is referenced by a variable.

JobType

Enumeration

Current state of the job.

Value	Description
Unknown	Job type is unknown.
SparkSession	Job type is from a spark session.
SparkBatch	Job type is from a spark batch.
JupyterSession	Job type is from jupyter session.

LivySession

Object

The livy session response

Name	Type	Description
attemptNumber	integer	Current attempt number.
cancellationReason	string	Reason for the job cancellation.
capacityId	string (uuid)	ID of the capacity.
consumerId	Principal: EntireTenantPrincipal GroupPrincipal ServicePrincipalPrincipal ServicePrincipalProfilePrincipal UserPrincipal	ID of the consumer.
creatorItem	ItemReferenceById	ID of the item creator. When `isHighConcurrency` is set to `true` this value might be different than `itemId`.
driverCores	integer	The number of CPU cores allocated to the Spark driver. Controls how much parallel processing the driver can handle.
driverMemory	integer	The amount of memory (in GB) assigned to the Spark driver process. Affects the driver's ability to handle job coordination and metadata.
dynamicAllocationMaxExecutors	integer	Sets the maximum number of executors that Spark's dynamic allocation can scale up to during job execution.
endDateTime	string (date-time)	Timestamp when the job ended in UTC, using the YYYY-MM-DDTHH:mm:ssZ format.
executorCores		The number of CPU cores allocated to each Spark executor. Determines how many tasks each executor can run in parallel.
executorMemory	integer	The amount of memory (in GB) assigned to each Spark executor process. Impacts how much data can be processed in memory per executor.
isDynamicAllocationEnabled	boolean	Flag indicating whether dynamic allocation is enabled for the Spark job.
isHighConcurrency	boolean	Flag indicating high concurrency.
item	ItemReferenceById	ID of the item.
itemName	string	Name of the item.
itemType	LivySessionItemType	The item type.
jobInstanceId	string (uuid)	ID of the job instance.
jobType	JobType	Current state of the job.
livyId	string (uuid)	ID of the Livy session or Livy batch.
livyName	string	Name of the Livy session or Livy batch.
livySessionItemResourceUri	string	The URI used to retrieve all Livy sessions for a given item.
maxNumberOfAttempts	integer	Maximum number of attempts.
numExecutors	integer	The total number of executors requested for the Spark job. Controls the parallelism and scalability of the job.
operationName	string	Name of the operation. Possible values include: Notebook run, Notebook HC run and Notebook pipeline run.
origin	Origin	Origin of the job.
queuedDuration	Duration	Duration for which the job was queued.
runningDuration	Duration	Time it took the job to run.
runtimeVersion	string	The fabric runtime version.
sparkApplicationId	string	A Spark application ID is a unique identifier assigned to each Apache Spark application. It also appears in the Spark UI.
startDateTime	string (date-time)	Timestamp when the job started in UTC, using the YYYY-MM-DDTHH:mm:ssZ format.
state	State	Current state of the job.
submittedDateTime	string (date-time)	Timestamp when the job was submitted in UTC, using the YYYY-MM-DDTHH:mm:ssZ format.
submitter	Principal: EntireTenantPrincipal GroupPrincipal ServicePrincipalPrincipal ServicePrincipalProfilePrincipal UserPrincipal	ID of the submitter.
totalDuration	Duration	Total duration of the job.

LivySessionItemType

Enumeration

The item type. Values are: Lakehouse, SparkJobDefinition, Notebook. Additional LivySessionItemType types may be added over time.

Value	Description
Lakehouse	Item is a lakehouse item.
SparkJobDefinition	Item is a spark job definition item.
Notebook	Item is a notebook item.

LivySessions

Object

A paginated list of livy sessions.

Name	Type	Description
continuationToken	string	The token for the next result set batch. If there are no more records, it's removed from the response.
continuationUri	string	The URI of the next result set batch. If there are no more records, it's removed from the response.
value	LivySession[]	A list of livy sessions.

Origin

Enumeration

Origin of the job.

Value	Description
SubmittedJob	Job is coming from submitted data source.
PendingJob	Job is coming from pending data source.

PrincipalType

Enumeration

The type of the principal. Additional principal types may be added over time.

Value	Description
User	Principal is a Microsoft Entra user principal.
ServicePrincipal	Principal is a Microsoft Entra service principal.
Group	Principal is a security group.
ServicePrincipalProfile	Principal is a service principal profile.
EntireTenant	Principal represents all tenant users.

ServicePrincipalDetails

Object

Service principal specific details. Applicable when the principal type is ServicePrincipal.

Name	Type	Description
aadAppId	string (uuid)	The service principal's Microsoft Entra AppId.

ServicePrincipalPrincipal

Object

Represents a Microsoft Entra service principal.

Name	Type	Description
displayName	string	The principal's display name.
id	string (uuid)	The principal's ID.
servicePrincipalDetails	ServicePrincipalDetails	Service principal specific details. Applicable when the principal type is `ServicePrincipal`.
type	string: ServicePrincipal	The type of the principal. Additional principal types may be added over time.

ServicePrincipalProfileDetails

Object

Service principal profile details. Applicable when the principal type is ServicePrincipalProfile.

Name	Type	Description
parentPrincipal	Principal: EntireTenantPrincipal GroupPrincipal ServicePrincipalPrincipal ServicePrincipalProfilePrincipal UserPrincipal	The service principal profile's parent principal.

ServicePrincipalProfilePrincipal

Object

Represents a service principal profile.

Name	Type	Description
displayName	string	The principal's display name.
id	string (uuid)	The principal's ID.
servicePrincipalProfileDetails	ServicePrincipalProfileDetails	Service principal profile details. Applicable when the principal type is `ServicePrincipalProfile`.
type	string: ServicePrincipalProfile	The type of the principal. Additional principal types may be added over time.

State

Enumeration

Current state of the job.

Value	Description
InProgress	Job is in running or is cancelling state.
Cancelled	Job got cancelled.
NotStarted	Job is queued, is starting or in library packaging state.
Succeeded	Job has stopped or is in success state.
Failed	Job failed or its session timed out.
Unknown	Job is in invalid state.

TimeUnit

Enumeration

The unit of time for the duration. Additional duration types may be added over time.

Value	Description
Seconds	Duration in seconds.
Minutes	Duration in minutes.
Hours	Duration in hours.
Days	Duration in days.

UserDetails

Object

User principal specific details. Applicable when the principal type is User.

Name	Type	Description
userPrincipalName	string	The user principal name.

UserPrincipal

Object

Represents a Microsoft Entra user principal.

Name	Type	Description
displayName	string	The principal's display name.
id	string (uuid)	The principal's ID.
type	string: User	The type of the principal. Additional principal types may be added over time.
userDetails	UserDetails	User principal specific details. Applicable when the principal type is `User`.