Livy Sessions - List Livy Sessions

Service:: Spark

API Version:: v1

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

Permissions

The caller must have viewer or higher workspace role.

Required Delegated Scopes

Workspace.Read.All or Workspace.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}/spark/livySessions

With optional parameters:

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

URI Parameters

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

Responses

Name	Type	Description
200 OK	LivySessions	OK -- Returns a list of all livy sessions associated to an itemId.
Other Status Codes	ErrorResponse	Common error codes: UnknownError - An error occurred.

Name

Type

Description

200 OK

LivySessions

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

Other Status Codes

ErrorResponse

Common error codes:

UnknownError - An error occurred.

Examples

List all livy sessions example

Sample request

HTTP

GET https://api.fabric.microsoft.com/v1/workspaces/f8113ba8-dd81-443e-811a-b385340f3f05/spark/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": "nb_itemName1",
      "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": ""
    },
    {
      "sparkApplicationId": "application_1730933685452_0001",
      "state": "Cancelled",
      "livyId": "4311f500-bf44-42e0-a0de-78dacb374397",
      "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": "7dee7699-2e81-4121-9a53-cc9025046197",
        "referenceType": "ById"
      },
      "itemName": "lh_itemName2",
      "itemType": "Lakehouse",
      "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": "7dee7699-2e81-4121-9a53-cc9025046197",
        "referenceType": "ById"
      },
      "cancellationReason": "User cancelled the Spark batch",
      "capacityId": "3c0cd366-dc28-4b6d-a525-4d415a8666e7",
      "operationName": "Batch Livy Run",
      "runtimeVersion": "1.3",
      "livySessionItemResourceUri": ""
    },
    {
      "sparkApplicationId": "application_1730933685452_0001",
      "state": "Cancelled",
      "livyId": "7611f500-bf44-42e0-a0de-78dacb374395",
      "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": "4aee7698-2e81-4121-9a53-cc9025046198",
        "referenceType": "ById"
      },
      "itemName": "sjd_itemName3",
      "itemType": "SparkJobDefinition",
      "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": "4aee7698-2e81-4121-9a53-cc9025046198",
        "referenceType": "ById"
      },
      "cancellationReason": "User cancelled the Spark batch",
      "capacityId": "3c0cd366-dc28-4b6d-a525-4d415a8666e7",
      "operationName": "Batch Livy Run",
      "runtimeVersion": "1.3",
      "livySessionItemResourceUri": ""
    }
  ]
}

Definitions

Name	Description
Duration	A duration.
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`.
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.
ItemType	The item type.
JobType	Current state of the job.
LivySession	The livy session response
LivySessions	A paginated list of livy sessions.
Origin	Origin of the job.
Principal	Represents an identity or a Microsoft Entra group.
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`.
ServicePrincipalProfileDetails	Service principal profile details. Applicable when the principal type is `ServicePrincipalProfile`.
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`.

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.

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	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.

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.

ItemType

Enumeration

The item type.

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

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	ID of the consumer.
creatorItem	ItemReferenceById	ID of the item creator. When `isHighConcurrency` is set to `true` this value might be different than `itemId`.
endDateTime	string (date-time)	Timestamp when the job ended in UTC, using the YYYY-MM-DDTHH:mm:ssZ format.
isHighConcurrency	boolean	Flag indicating high concurrency.
item	ItemReferenceById	ID of the item.
itemName	string	Name of the item.
itemType	ItemType	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.
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	ID of the submitter.
totalDuration	Duration	Total duration of the job.

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.

Principal

Object

Represents an identity or a Microsoft Entra 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.
servicePrincipalDetails	ServicePrincipalDetails	Service principal specific details. Applicable when the principal type is `ServicePrincipal`.
servicePrincipalProfileDetails	ServicePrincipalProfileDetails	Service principal profile details. Applicable when the principal type is `ServicePrincipalProfile`.
type	PrincipalType	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`.

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.

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.

ServicePrincipalProfileDetails

Object

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

Name	Type	Description
parentPrincipal	Principal	The service principal profile's parent principal.

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.

Share via

Livy Sessions - List Livy Sessions

Permissions

Required Delegated Scopes

Microsoft Entra supported identities

Interface

URI Parameters

Responses

Examples

List all livy sessions example

Sample request

Sample response

Definitions

Duration

ErrorRelatedResource

ErrorResponse

ErrorResponseDetails

GroupDetails

GroupType

ItemReferenceById

ItemReferenceType

ItemType

JobType

LivySession

LivySessions

Origin

Principal

PrincipalType

ServicePrincipalDetails

ServicePrincipalProfileDetails

State

TimeUnit

UserDetails