Livy Sessions - Get Livy Session

Service:: Notebook

API Version:: v1

Returns properties of the specified livy session.

Permissions

The caller must have viewer or higher workspace role.

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/{livyId}

URI Parameters

Name	In	Required	Type	Description
livyId	path	True	string	The session identifier.
notebookId	path	True	string (uuid)	The notebook ID.
workspaceId	path	True	string	The workspace identifier.

Responses

Name	Type	Description
200 OK	LivySession	OK -- Returns a livy session by its id.
Other Status Codes	ErrorResponse	Common error codes: SparkCoreSessionNotFound - Livy identifier does not exist SparkCoreUnexpectedException - Unhandled exception ocurred.

Name

Type

Description

200 OK

LivySession

OK -- Returns a livy session by its id.

Other Status Codes

ErrorResponse

Common error codes:

SparkCoreSessionNotFound - Livy identifier does not exist
SparkCoreUnexpectedException - Unhandled exception ocurred.

Examples

Get a livy session example

Sample request

HTTP

GET https://api.fabric.microsoft.com/v1/workspaces/f8113ba8-dd81-443e-811a-b385340f3f05/notebooks/8cee7699-2e81-4121-9a53-cc9025046193/livySessions/9611f500-bf44-42e0-a0de-78dacb374398

Sample response

Status code:: 200

{
  "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": ""
}

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 type of the item. Additional item types may be added over time.
JobType	Current state of the job.
LivySession	The livy session response
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
DistributionList	Principal is a distribution list.
SecurityGroup	Principal is a security group.
Unknown	Principal group type is unknown.

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 type of the item. Additional item types may be added over time.

Value	Description
ApacheAirflowJob	An ApacheAirflowJob.
CopyJob	A Copy job.
Dashboard	PowerBI dashboard.
DataPipeline	A data pipeline.
Dataflow	A Dataflow.
Datamart	PowerBI datamart.
DigitalTwinBuilder	A DigitalTwinBuilder.
DigitalTwinBuilderFlow	A Digital Twin Builder Flow.
Environment	An environment.
Eventhouse	An eventhouse.
Eventstream	An eventstream.
GraphQLApi	An API for GraphQL item.
KQLDashboard	A KQL dashboard.
KQLDatabase	A KQL database.
KQLQueryset	A KQL queryset.
Lakehouse	A lakehouse.
MLExperiment	A machine learning experiment.
MLModel	A machine learning model.
MirroredAzureDatabricksCatalog	A mirrored azure databricks catalog.
MirroredDatabase	A mirrored database.
MirroredWarehouse	A mirrored warehouse.
MountedDataFactory	A MountedDataFactory.
Notebook	A notebook.
PaginatedReport	PowerBI paginated report.
Reflex	A Reflex.
Report	PowerBI report.
SQLDatabase	A SQLDatabase.
SQLEndpoint	An SQL endpoint.
SemanticModel	PowerBI semantic model.
SparkJobDefinition	A spark job definition.
VariableLibrary	A VariableLibrary.
Warehouse	A warehouse.
WarehouseSnapshot	A Warehouse snapshot.

JobType

Enumeration

Current state of the job.

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

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.

Origin

Enumeration

Origin of the job.

Value	Description
PendingJob	Job is coming from pending data source.
SubmittedJob	Job is coming from submitted 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
Group	Principal is a security group.
ServicePrincipal	Principal is a Microsoft Entra service principal.
ServicePrincipalProfile	Principal is a service principal profile.
User	Principal is a Microsoft Entra user principal.

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
Cancelled	Job got cancelled.
Failed	Job failed or its session timed out.
InProgress	Job is in running or is cancelling state.
NotStarted	Job is queued, is starting or in library packaging state.
Succeeded	Job has stopped or is in success state.
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
Days	Duration in days.
Hours	Duration in hours.
Minutes	Duration in minutes.
Seconds	Duration in seconds.

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 - Get Livy Session

Permissions

Required Delegated Scopes

Microsoft Entra supported identities

Interface

URI Parameters

Responses

Examples

Get a livy session example

Sample request

Sample response

Definitions

Duration

ErrorRelatedResource

ErrorResponse

ErrorResponseDetails

GroupDetails

GroupType

ItemReferenceById

ItemReferenceType

ItemType

JobType

LivySession

Origin

Principal

PrincipalType

ServicePrincipalDetails

ServicePrincipalProfileDetails

State

TimeUnit

UserDetails