Microsoft Fabric Pool Activations API

openapi: 3.2.0
info:
  title: Microsoft Fabric Workload Items REST Pool Activations API
  version: v1
  x-source: 'https://github.com/microsoft/fabric-rest-api-specs (bundled from openapi/_original/fabric-rest-api-specs: anomalyDetector/swagger.json, apacheAirflowJob/swagger.json, appBackend/swagger.json, azureDatabricksStorage/swagger.json, copyJob/swagger.json, cosmosDbDatabase/swagger.json, dashboard/swagger.json, dataAgent/swagger.json, dataBuildToolJob/swagger.json, dataPipeline/swagger.json, dataflow/swagger.json, datamart/swagger.json, deploymentPlan/swagger.json, digitalTwinBuilder/swagger.json, digitalTwinBuilderFlow/swagger.json, environment/swagger.json, eventSchemaSet/swagger.json, eventhouse/swagger.json, eventstream/swagger.json, graphModel/swagger.json, graphQLApi/swagger.json, graphQuerySet/swagger.json, kqlDashboard/swagger.json, kqlDatabase/swagger.json, kqlQueryset/swagger.json, lakehouse/swagger.json, map/swagger.json, mirroredAzureDatabricksCatalog/swagger.json, mirroredCatalog/swagger.json, mirroredDatabase/swagger.json, mirroredWarehouse/swagger.json, mlExperiment/swagger.json, mlModel/swagger.json, monitoring/swagger.json, mountedDataFactory/swagger.json, notebook/swagger.json, ontology/swagger.json, operationsAgent/swagger.json, orgApp/swagger.json, orgAppAudience/swagger.json, paginatedReport/swagger.json, plan/swagger.json, policySet/swagger.json, realTimeIntelligence/swagger.json, reflex/swagger.json, report/swagger.json, semanticModel/swagger.json, snowflakeDatabase/swagger.json, spark/swagger.json, sparkjobdefinition/swagger.json, sqlDatabase/swagger.json, sqlEndpoint/swagger.json, userDataFunction/swagger.json, variableLibrary/swagger.json, warehouse/swagger.json)'
servers:
- url: https://api.fabric.microsoft.com/v1
security: []
tags:
- name: PoolActivations
paths:
  /workspaces/{workspaceId}/environments/{environmentId}/poolActivations:
    get:
      tags:
      - PoolActivations
      summary: Lists pool activations for the specified environment
      description: 'Returns pool activation history for a custom live pool associated with the specified environment. This API supports pagination and filtering by activation state.


        This API supports pagination.


        ## Permissions


        The caller must have *read* permissions for the environment item.


        ## Required Delegated Scopes


        Environment.Read.All or Environment.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'
      operationId: PoolActivations_ListPoolActivations
      x-ms-pageable:
        nextLinkName: continuationUri
      parameters:
      - in: path
        name: workspaceId
        description: The workspace identifier.
        required: true
        schema:
          type: string
          format: uuid
      - in: path
        name: environmentId
        description: The environment identifier.
        required: true
        schema:
          type: string
          format: uuid
      - in: query
        name: continuationToken
        description: A token for retrieving the next page of results.
        required: false
        schema:
          type: string
      - in: query
        name: pageSize
        description: The requested number of items per page. The server may return fewer items. If unspecified or exceeds the server maximum, the server uses its configured default.
        required: false
        schema:
          type: integer
          format: int32
      - in: query
        name: filter
        description: 'An expression that filters the collection. Supported filter: `state eq ''<state>''`. Supported values for `<state>`: `NotStarted`, `InProgress`, `Succeeded`, `Failed`, `Cancelled`, `Unknown`.'
        required: false
        schema:
          type: string
      responses:
        '200':
          description: Request completed successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PoolActivations'
        '429':
          description: 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.
          x-ms-error-response: true
          headers:
            Retry-After:
              description: The number of seconds to wait before retrying the request.
              schema:
                type: integer
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        default:
          description: 'Common error codes:


            * SparkCoreBadWebRequest - The filter expression is malformed or uses an unsupported operator/field.


            * SparkCoreItemNotFound - The specified environment does not exist.


            * SparkCoreUnexpectedException - An unhandled exception occurred.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /workspaces/{workspaceId}/environments/{environmentId}/poolActivations/{activationId}:
    get:
      tags:
      - PoolActivations
      summary: Gets properties of the specified pool activation
      description: 'Returns detailed properties of a single pool activation, including Spark configuration and resource breakdown diagnostics.


        ## Permissions


        The caller must have *read* permissions for the environment item.


        ## Required Delegated Scopes


        Environment.Read.All or Environment.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'
      operationId: PoolActivations_GetPoolActivation
      parameters:
      - in: path
        name: workspaceId
        description: The workspace identifier.
        required: true
        schema:
          type: string
          format: uuid
      - in: path
        name: environmentId
        description: The environment identifier.
        required: true
        schema:
          type: string
          format: uuid
      - in: path
        name: activationId
        description: The pool activation identifier.
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Request completed successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PoolActivationDetails'
        '429':
          description: 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.
          x-ms-error-response: true
          headers:
            Retry-After:
              description: The number of seconds to wait before retrying the request.
              schema:
                type: integer
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        default:
          description: 'Common error codes:


            * SparkCoreItemNotFound - The specified environment does not exist.


            * SparkCoreJobNotFound - The specified pool activation does not exist.


            * SparkCoreUnexpectedException - An unhandled exception occurred.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    ErrorResponse:
      description: The error response.
      required:
      - message
      - errorCode
      allOf:
      - $ref: '#/components/schemas/ErrorResponseDetails'
      properties:
        requestId:
          type: string
          format: uuid
          description: ID of the request associated with the error.
          readOnly: true
        moreDetails:
          description: List of additional error details.
          type: array
          items:
            $ref: '#/components/schemas/ErrorResponseDetails'
          readOnly: true
        isRetriable:
          type: boolean
          description: When true, the request can be retried. Use the `Retry-After` response header to determine the delay, if available.
          readOnly: true
    SparkComputeConfiguration:
      description: Common Spark compute configuration properties.
      type: object
      properties:
        driverMemory:
          description: The driver memory allocation including the unit suffix, for example `7g` or `28g`.
          type: string
        driverCores:
          description: The number of CPU cores allocated to the driver.
          type: integer
          format: int32
        executorMemory:
          description: The executor memory allocation including the unit suffix, for example `7g` or `28g`.
          type: string
        executorCores:
          description: The number of CPU cores allocated to each executor.
          type: integer
          format: int32
    ResourceStatusSummary:
      description: The summary of custom live pool activation resources grouped by user-facing lifecycle status.
      type: object
      properties:
        starting:
          description: The number of resources currently provisioning.
          type: integer
          format: int32
        ready:
          description: The number of resources warmed up and available.
          type: integer
          format: int32
        acquired:
          description: The number of resources acquired by (actively assigned to) a session.
          type: integer
          format: int32
        stopping:
          description: The number of resources being decommissioned.
          type: integer
          format: int32
        deactivated:
          description: The number of resources intentionally deactivated by policy.
          type: integer
          format: int32
        expired:
          description: The number of resources that exceeded their lifetime.
          type: integer
          format: int32
        cancelled:
          description: The number of resources cancelled before completion.
          type: integer
          format: int32
        failed:
          description: The number of resources that failed to provision.
          type: integer
          format: int32
    PoolActivations:
      description: A paginated list of pool activations.
      type: object
      required:
      - value
      allOf:
      - $ref: '#/components/schemas/PaginatedResponse'
      properties:
        value:
          description: A list of pool activations.
          type: array
          items:
            $ref: '#/components/schemas/PoolActivation'
    ErrorParameter:
      description: A structured parameter providing additional machine-readable context about an error.
      type: object
      properties:
        name:
          type: string
          description: The parameter identifier.
          readOnly: true
        value:
          type: string
          description: The parameter value.
          readOnly: true
        message:
          type: string
          description: A human-readable description of the parameter's meaning.
          readOnly: true
    ErrorResponseDetails:
      description: The error response details.
      type: object
      required:
      - message
      - errorCode
      properties:
        errorCode:
          type: string
          description: A specific identifier that provides information about an error condition, allowing for standardized communication between our service and its users.
          readOnly: true
        message:
          type: string
          description: A human readable representation of the error.
          readOnly: true
        relatedResource:
          $ref: '#/components/schemas/ErrorRelatedResource'
        parameters:
          description: Structured parameters providing additional machine-readable context about the error.
          type: array
          items:
            $ref: '#/components/schemas/ErrorParameter'
          readOnly: true
    JobHistoryStatus:
      description: The lifecycle state of a pool activation. Additional JobHistoryStatus types may be added over time.
      type: string
      enum:
      - NotStarted
      - InProgress
      - Succeeded
      - Failed
      - Cancelled
      - Unknown
      x-ms-enum:
        name: State
        modelAsString: true
        values:
        - value: NotStarted
          description: The activation has not yet started.
        - value: InProgress
          description: The activation is currently in progress.
        - value: Succeeded
          description: The activation completed successfully.
        - value: Failed
          description: The activation failed.
        - value: Cancelled
          description: The activation was cancelled.
        - value: Unknown
          description: The activation state is unknown.
    ErrorRelatedResource:
      description: The error related resource details object.
      type: object
      required:
      - resourceId
      - resourceType
      properties:
        resourceId:
          type: string
          description: The resource ID that's involved in the error.
          readOnly: true
        resourceType:
          type: string
          description: The type of the resource that's involved in the error.
          readOnly: true
    SparkConfiguration:
      description: The Spark configuration for a pool activation.
      type: object
      allOf:
      - $ref: '#/components/schemas/SparkComputeConfiguration'
      properties:
        numExecutors:
          description: The number of executors.
          type: integer
          format: int32
        isDynamicAllocationEnabled:
          description: Whether dynamic allocation was enabled for the activation. When `false`, the activation used a fixed executor count from `numExecutors` and no dynamic scaling was applied.
          type: boolean
    CustomLivePoolSettings:
      description: Live pool hydration settings on the environment's spark compute.
      type: object
      properties:
        maxClustersToHydrate:
          description: 'Maximum number of clusters to pre-hydrate during each activation cycle. Minimum: 1. The maximum allowed value is determined by the capacity size and is exposed on the instance pool settings as `InstancePool.maxClustersToHydrateLimit`.'
          format: int32
          type: integer
          minimum: 1
        clusterIdleTimeout:
          description: 'Idle-time threshold after which a hydrated cluster is released, using the ISO 8601 duration format. Minimum: PT20M. Maximum: PT24H.'
          format: duration
          type: string
        customLivePoolLifespan:
          description: 'Maximum lifetime of a live pool activation, using the ISO 8601 duration format. The live pool job runs for this duration and then terminates. Minimum: PT30M. Maximum: PT24H.'
          format: duration
          type: string
    PaginatedResponse:
      properties:
        continuationToken:
          type: string
          description: The token for the next result set batch. If there are no more records, it's removed from the response.
        continuationUri:
          type: string
          description: The URI of the next result set batch. If there are no more records, it's removed from the response.
    PoolActivationDetails:
      description: A pool activation details object with extended diagnostic properties.
      type: object
      required:
      - sparkConfiguration
      allOf:
      - $ref: '#/components/schemas/PoolActivation'
      properties:
        poolName:
          description: The pool display name.
          type: string
        sparkConfiguration:
          $ref: '#/components/schemas/SparkConfiguration'
        resourceStatusSummary:
          $ref: '#/components/schemas/ResourceStatusSummary'
    PoolActivation:
      description: A pool activation object.
      type: object
      allOf:
      - $ref: '#/components/schemas/CustomLivePoolSettings'
      properties:
        jobInstanceId:
          description: The pool activation job instance identifier.
          type: string
          format: uuid
        name:
          description: The pool activation name.
          type: string
        capacityId:
          description: The capacity identifier.
          type: string
          format: uuid
        state:
          $ref: '#/components/schemas/JobHistoryStatus'
        scheduledStartDateTime:
          description: The scheduled start time in UTC, using the YYYY-MM-DDTHH:mm:ssZ format.
          type: string
        startDateTime:
          description: The actual start time in UTC, using the YYYY-MM-DDTHH:mm:ssZ format.
          type: string
        scheduledEndDateTime:
          description: The scheduled end time in UTC, using the YYYY-MM-DDTHH:mm:ssZ format.
          type: string
        endDateTime:
          description: The actual end time in UTC, using the YYYY-MM-DDTHH:mm:ssZ format. Omitted if the activation is ongoing.
          type: string
        isRecurring:
          description: Whether the activation recurs on a schedule.
          type: boolean
        cancellationReason:
          description: The reason for cancellation, if applicable.
          type: string
        jobType:
          description: The monitoring job type classification.
          type: string
        runtimeVersion:
          description: The Fabric runtime version used for the activation.
          type: string