Databricks Jobs API

openapi: 3.1.0
info:
  title: Databricks REST API
  description: >-
    The Databricks REST API provides programmatic access to manage Databricks
    workspace resources including clusters, jobs, and workspace objects. All API
    endpoints require authentication using a personal access token or OAuth token
    passed via the Authorization header. The base URL is specific to your
    Databricks workspace deployment region.
  version: 2.1.0
  contact:
    name: Databricks
    url: https://www.databricks.com/company/contact
    email: [email protected]
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0
  termsOfService: https://www.databricks.com/legal/terms-of-use
servers:
- url: https://{workspace_host}/api
  description: Databricks workspace API endpoint
  variables:
    workspace_host:
      default: adb-1234567890123456.7.azuredatabricks.net
      description: >-
        The hostname of your Databricks workspace. Format varies by cloud
        provider (e.g., adb-<workspace-id>.<random>.azuredatabricks.net for
        Azure, <workspace-id>.cloud.databricks.com for AWS).
security:
- bearerAuth: []
tags:
- name: Clusters
  description: >-
    Manage Databricks clusters for running data engineering and data science
    workloads on Apache Spark.
- name: Jobs
  description: >-
    Create and manage automated workloads including notebooks, JARs, Python
    scripts, and multi-task workflows.
- name: Workspace
  description: >-
    Manage workspace objects such as notebooks, folders, and libraries.
paths:
  /2.0/clusters/create:
    post:
      operationId: createCluster
      summary: Databricks Create a New Cluster
      description: >-
        Creates a new Spark cluster. This method acquires new instances from the
        cloud provider and starts the Spark driver and worker processes. The
        cluster is created asynchronously; use the cluster_id returned to poll
        for status.
      tags:
      - Clusters
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateClusterRequest'
            examples:
              CreateclusterRequestExample:
                summary: Default createCluster request
                x-microcks-default: true
                value:
                  cluster_name: example_value
                  spark_version: example_value
                  node_type_id: '500123'
                  driver_node_type_id: '500123'
                  num_workers: 10
                  autoscale:
                    min_workers: 10
                    max_workers: 10
                  spark_conf: example_value
                  aws_attributes:
                    first_on_demand: 10
                    availability: SPOT
                    zone_id: '500123'
                    instance_profile_arn: example_value
                    spot_bid_price_percent: 10
                    ebs_volume_type: GENERAL_PURPOSE_SSD
                    ebs_volume_count: 10
                    ebs_volume_size: 10
                  azure_attributes:
                    first_on_demand: 10
                    availability: SPOT_AZURE
                    spot_bid_max_price: 42.5
                  gcp_attributes:
                    use_preemptible_executors: true
                    google_service_account: example_value
                    availability: GCP_PREEMPTIBLE
                  custom_tags: example_value
                  spark_env_vars: example_value
                  autotermination_minutes: 10
                  enable_elastic_disk: true
                  instance_pool_id: '500123'
                  policy_id: '500123'
                  enable_local_disk_encryption: true
                  runtime_engine: STANDARD
                  data_security_mode: NONE
                  single_user_name: example_value
                  init_scripts:
                  - workspace: {}
                    volumes: {}
                    dbfs: {}
                  ssh_public_keys:
                  - example_value
      responses:
        '200':
          description: Cluster creation initiated successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  cluster_id:
                    type: string
                    description: The unique identifier of the newly created cluster.
                    examples:
                    - '1234-567890-abcde123'
              examples:
                Createcluster200Example:
                  summary: Default createCluster 200 response
                  x-microcks-default: true
                  value:
                    cluster_id: '500123'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /2.0/clusters/list:
    get:
      operationId: listClusters
      summary: Databricks List All Clusters
      description: >-
        Returns information about all clusters in the workspace, including
        terminated clusters. Clusters are ordered by cluster_id.
      tags:
      - Clusters
      parameters:
      - name: can_use_client
        in: query
        required: false
        description: Filter clusters by client compatibility.
        schema:
          type: string
        example: example_value
      responses:
        '200':
          description: Successfully retrieved the list of clusters.
          content:
            application/json:
              schema:
                type: object
                properties:
                  clusters:
                    type: array
                    items:
                      $ref: '#/components/schemas/ClusterDetails'
              examples:
                Listclusters200Example:
                  summary: Default listClusters 200 response
                  x-microcks-default: true
                  value:
                    clusters:
                    - cluster_id: '500123'
                      cluster_name: example_value
                      spark_version: example_value
                      node_type_id: '500123'
                      driver_node_type_id: '500123'
                      num_workers: 10
                      state: PENDING
                      state_message: example_value
                      start_time: 10
                      terminated_time: 10
                      last_state_loss_time: 10
                      last_activity_time: 10
                      last_restarted_time: 10
                      creator_user_name: example_value
                      cluster_source: UI
                      spark_conf: example_value
                      custom_tags: example_value
                      spark_env_vars: example_value
                      autotermination_minutes: 10
                      enable_elastic_disk: true
                      instance_pool_id: '500123'
                      policy_id: '500123'
                      data_security_mode: example_value
                      single_user_name: example_value
                      runtime_engine: example_value
                      default_tags: example_value
                      cluster_log_status:
                        last_attempted: 10
                        last_exception: example_value
                      termination_reason:
                        code: example_value
                        type: example_value
                        parameters: example_value
                      disk_spec:
                        disk_count: 10
                        disk_size: 10
                        disk_type: {}
                      executors:
                      - {}
                      jdbc_port: 10
                      spark_context_id: '500123'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /2.0/clusters/get:
    get:
      operationId: getCluster
      summary: Databricks Get Cluster Details
      description: >-
        Retrieves detailed information about a cluster, including its current
        state, configuration, and runtime properties.
      tags:
      - Clusters
      parameters:
      - name: cluster_id
        in: query
        required: true
        description: The unique identifier of the cluster.
        schema:
          type: string
        example: '500123'
      responses:
        '200':
          description: Successfully retrieved cluster details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClusterDetails'
              examples:
                Getcluster200Example:
                  summary: Default getCluster 200 response
                  x-microcks-default: true
                  value:
                    cluster_id: '500123'
                    cluster_name: example_value
                    spark_version: example_value
                    node_type_id: '500123'
                    driver_node_type_id: '500123'
                    num_workers: 10
                    autoscale:
                      min_workers: 10
                      max_workers: 10
                    state: PENDING
                    state_message: example_value
                    start_time: 10
                    terminated_time: 10
                    last_state_loss_time: 10
                    last_activity_time: 10
                    last_restarted_time: 10
                    creator_user_name: example_value
                    cluster_source: UI
                    spark_conf: example_value
                    custom_tags: example_value
                    spark_env_vars: example_value
                    autotermination_minutes: 10
                    enable_elastic_disk: true
                    instance_pool_id: '500123'
                    policy_id: '500123'
                    data_security_mode: example_value
                    single_user_name: example_value
                    runtime_engine: example_value
                    default_tags: example_value
                    cluster_log_status:
                      last_attempted: 10
                      last_exception: example_value
                    termination_reason:
                      code: example_value
                      type: example_value
                      parameters: example_value
                    disk_spec:
                      disk_count: 10
                      disk_size: 10
                      disk_type:
                        azure_disk_volume_type: example_value
                        ebs_volume_type: example_value
                    driver:
                      private_ip: example_value
                      public_dns: example_value
                      node_id: '500123'
                      instance_id: '500123'
                      start_timestamp: 10
                      host_private_ip: example_value
                    executors:
                    - private_ip: example_value
                      public_dns: example_value
                      node_id: '500123'
                      instance_id: '500123'
                      start_timestamp: 10
                      host_private_ip: example_value
                    jdbc_port: 10
                    spark_context_id: '500123'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /2.0/clusters/start:
    post:
      operationId: startCluster
      summary: Databricks Start a Terminated Cluster
      description: >-
        Starts a terminated cluster given its cluster_id. This is similar to
        creating a cluster except it uses the configuration of the previously
        terminated cluster.
      tags:
      - Clusters
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - cluster_id
              properties:
                cluster_id:
                  type: string
                  description: The cluster to start.
            examples:
              StartclusterRequestExample:
                summary: Default startCluster request
                x-microcks-default: true
                value:
                  cluster_id: '500123'
      responses:
        '200':
          description: Cluster start initiated successfully.
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /2.0/clusters/restart:
    post:
      operationId: restartCluster
      summary: Databricks Restart a Cluster
      description: >-
        Restarts a Spark cluster given its cluster_id. If the cluster is not in
        a RUNNING state, nothing happens.
      tags:
      - Clusters
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - cluster_id
              properties:
                cluster_id:
                  type: string
                  description: The cluster to restart.
            examples:
              RestartclusterRequestExample:
                summary: Default restartCluster request
                x-microcks-default: true
                value:
                  cluster_id: '500123'
      responses:
        '200':
          description: Cluster restart initiated successfully.
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /2.0/clusters/delete:
    post:
      operationId: terminateCluster
      summary: Databricks Terminate a Cluster
      description: >-
        Terminates a Spark cluster given its cluster_id. The cluster is removed
        after being terminated. Use the permanent-delete endpoint if you want to
        remove the cluster configuration entirely.
      tags:
      - Clusters
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - cluster_id
              properties:
                cluster_id:
                  type: string
                  description: The cluster to terminate.
            examples:
              TerminateclusterRequestExample:
                summary: Default terminateCluster request
                x-microcks-default: true
                value:
                  cluster_id: '500123'
      responses:
        '200':
          description: Cluster termination initiated successfully.
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /2.0/clusters/permanent-delete:
    post:
      operationId: permanentDeleteCluster
      summary: Databricks Permanently Delete a Cluster
      description: >-
        Permanently deletes a Spark cluster. If the cluster is running, it is
        terminated and resources are asynchronously removed. If the cluster is
        terminated, it is immediately removed. A cluster can only be permanently
        deleted by an admin or the cluster creator.
      tags:
      - Clusters
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - cluster_id
              properties:
                cluster_id:
                  type: string
                  description: The cluster to permanently delete.
            examples:
              PermanentdeleteclusterRequestExample:
                summary: Default permanentDeleteCluster request
                x-microcks-default: true
                value:
                  cluster_id: '500123'
      responses:
        '200':
          description: Cluster permanently deleted.
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /2.0/clusters/edit:
    post:
      operationId: editCluster
      summary: Databricks Edit Cluster Configuration
      description: >-
        Edits the configuration of a cluster to match the provided attributes.
        The cluster must be in a RUNNING or TERMINATED state. If the cluster is
        running, it will be restarted to apply the changes.
      tags:
      - Clusters
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EditClusterRequest'
            examples:
              EditclusterRequestExample:
                summary: Default editCluster request
                x-microcks-default: true
                value:
                  cluster_id: '500123'
                  cluster_name: example_value
                  spark_version: example_value
                  node_type_id: '500123'
                  driver_node_type_id: '500123'
                  num_workers: 10
                  autoscale:
                    min_workers: 10
                    max_workers: 10
                  spark_conf: example_value
                  custom_tags: example_value
                  spark_env_vars: example_value
                  autotermination_minutes: 10
                  enable_elastic_disk: true
                  instance_pool_id: '500123'
                  policy_id: '500123'
                  data_security_mode: NONE
                  single_user_name: example_value
                  runtime_engine: STANDARD
      responses:
        '200':
          description: Cluster configuration updated successfully.
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /2.0/clusters/events:
    post:
      operationId: listClusterEvents
      summary: Databricks List Cluster Events
      description: >-
        Retrieves a list of events about the activity of a cluster. Events are
        returned in reverse chronological order. This endpoint can be used to
        audit cluster activity and monitor lifecycle changes.
      tags:
      - Clusters
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - cluster_id
              properties:
                cluster_id:
                  type: string
                  description: The ID of the cluster to retrieve events for.
                start_time:
                  type: integer
                  format: int64
                  description: Start timestamp in milliseconds for the event query range.
                end_time:
                  type: integer
                  format: int64
                  description: End timestamp in milliseconds for the event query range.
                order:
                  type: string
                  enum:
                  - DESC
                  - ASC
                  description: Sort order for results.
                event_types:
                  type: array
                  items:
                    type: string
                    enum:
                    - CREATING
                    - DID_NOT_EXPAND_DISK
                    - EXPANDED_DISK
                    - FAILED_TO_EXPAND_DISK
                    - INIT_SCRIPTS_STARTING
                    - INIT_SCRIPTS_FINISHED
                    - STARTING
                    - RESTARTING
                    - TERMINATING
                    - EDITED
                    - RUNNING
                    - RESIZING
                    - UPSIZE_COMPLETED
                    - NODES_LOST
                    - DRIVER_HEALTHY
                    - DRIVER_NOT_RESPONDING
                    - DRIVER_UNAVAILABLE
                    - SPARK_EXCEPTION
                    - PINNED
                    - UNPINNED
                  description: Filter by specific event types.
                offset:
                  type: integer
                  format: int64
                  description: Offset for pagination.
                limit:
                  type: integer
                  format: int64
                  description: Maximum number of events to return (max 500).
            examples:
              ListclustereventsRequestExample:
                summary: Default listClusterEvents request
                x-microcks-default: true
                value:
                  cluster_id: '500123'
                  start_time: 10
                  end_time: 10
                  order: DESC
                  event_types:
                  - CREATING
                  offset: 10
                  limit: 10
      responses:
        '200':
          description: Successfully retrieved cluster events.
          content:
            application/json:
              schema:
                type: object
                properties:
                  events:
                    type: array
                    items:
                      $ref: '#/components/schemas/ClusterEvent'
                  next_page:
                    type: object
                    properties:
                      cluster_id:
                        type: string
                      end_time:
                        type: integer
                        format: int64
                      offset:
                        type: integer
                        format: int64
                  total_count:
                    type: integer
                    format: int64
              examples:
                Listclusterevents200Example:
                  summary: Default listClusterEvents 200 response
                  x-microcks-default: true
                  value:
                    events:
                    - cluster_id: '500123'
                      timestamp: 10
                      type: example_value
                      details:
                        current_num_workers: 10
                        target_num_workers: 10
                        previous_attributes: example_value
                        attributes: example_value
                        previous_cluster_size: example_value
                        cluster_size: example_value
                        cause: example_value
                        reason: {}
                    next_page:
                      cluster_id: '500123'
                      end_time: 10
                      offset: 10
                    total_count: 10
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /2.1/jobs/create:
    post:
      operationId: createJob
      summary: Databricks Create a New Job
      description: >-
        Creates a new job with the provided settings. The job can be configured
        with a single task or multiple tasks with dependencies forming a
        directed acyclic graph (DAG).
      tags:
      - Jobs
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateJobRequest'
            examples:
              CreatejobRequestExample:
                summary: Default createJob request
                x-microcks-default: true
                value:
                  name: Example Title
                  tasks:
                  - task_key: example_value
                    description: A sample description.
                    depends_on: {}
                    existing_cluster_id: '500123'
                    job_cluster_key: example_value
                    notebook_task: {}
                    spark_jar_task: {}
                    spark_python_task: {}
                    spark_submit_task: {}
                    pipeline_task: {}
                    python_wheel_task: {}
                    sql_task: {}
                    dbt_task: {}
                    run_if: ALL_SUCCESS
                    timeout_seconds: 10
                    max_retries: 10
                    min_retry_interval_millis: 10
                    retry_on_timeout: true
                    libraries: {}
                  job_clusters:
                  - job_cluster_key: example_value
                  email_notifications:
                    on_start:
                    - {}
                    on_success:
                    - {}
                    on_failure:
                    - {}
                    on_duration_warning_threshold_exceeded:
                    - {}
                    no_alert_for_skipped_runs: true
                  webhook_notifications:
                    on_start:
                    - {}
                    on_success:
                    - {}
                    on_failure:
                    - {}
                    on_duration_warning_threshold_exceeded:
                    - {}
                  notification_settings:
                    no_alert_for_skipped_runs: true
                    no_alert_for_canceled_runs: true
                  timeout_seconds: 10
                  schedule:
                    quartz_cron_expression: example_value
                    timezone_id: '500123'
                    pause_status: PAUSED
                  continuous:
                    pause_status: PAUSED
                  trigger:
                    pause_status: PAUSED
                    file_arrival:
                      url: https://www.example.com
                      min_time_between_triggers_seconds: 10
                      wait_after_last_change_seconds: 10
                  max_concurrent_runs: 10
                  git_source:
                    git_url: https://www.example.com
                    git_provider: gitHub
                    git_branch: example_value
                    git_tag: example_value
                    git_commit: example_value
                  tags: example_value
                  format: SINGLE_TASK
                  queue:
                    enabled: true
                  parameters:
                  - name: Example Title
                    default: example_value
                  run_as:
                    user_name: example_value
                    service_principal_name: example_value
                  access_control_list:
                  - user_name: example_value
                    group_name: example_value
                    service_principal_name: example_value
                    permission_level: CAN_MANAGE
      responses:
        '200':
          description: Job created successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  job_id:
                    type: integer
                    format: int64
                    description: The canonical identifier for the newly created job.
                    examples:
                    - 11223344
              examples:
                Createjob200Example:
                  summary: Default createJob 200 response
                  x-microcks-default: true
                  value:
                    job_id: '500123'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /2.1/jobs/list:
    get:
      operationId: listJobs
      summary: Databricks List All Jobs
      description: >-
        Retrieves a list of jobs in the workspace. Results are paginated and can
        be filtered by name.
      tags:
      - Jobs
      parameters:
      - name: limit
        in: query
        required: false
        description: >-
          The number of jobs to return. This value must be greater than 0 and
          less than or equal to 25. The default value is 20.
        schema:
          type: integer
          default: 20
          maximum: 25
        example: 10
      - name: offset
        in: query
        required: false
        description: The offset of the first job to return.
        schema:
          type: integer
          default: 0
        example: 10
      - name: name
        in: query
        required: false
        description: >-
          A filter on the list based on the exact (case-insensitive) job name.
        schema:
          type: string
        example: Example Title
      - name: expand_tasks
        in: query
        required: false
        description: Whether to include task and cluster details in the response.
        schema:
          type: boolean
          default: false
        example: true
      responses:
        '200':
          description: Successfully retrieved the list of jobs.
          content:
            application/json:
              schema:
                type: object
                properties:
                  jobs:
                    type: array
                    items:
                      $ref: '#/components/schemas/Job'
                  has_more:
                    type: boolean
                    description: Whether there are more jobs to list.
              examples:
                Listjobs200Example:
                  summary: Default listJobs 200 response
                  x-microcks-default: true
                  value:
                    jobs:
                    - job_id: '500123'
                      creator_user_name: example_value
                      run_as_user_name: example_value
                      created_time: 10
                    has_more: true
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /2.1/jobs/get:
    get:
      operationId: getJob
      summary: Databricks Get a Job
      description: >-
        Retrieves the details of a single job, including its settings, creator,
        and run history summary.
      tags:
      - Jobs
      parameters:
      - name: job_id
        in: query
        required: true
        description: The canonical identifier of the job to retrieve.
        schema:
          type: integer
          format: int64
        example: '500123'
      responses:
        '200':
          description: Successfully retrieved the job.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Job'
              examples:
                Getjob200Example:
                  summary: Default getJob 200 response
                  x-microcks-default: true
                  value:
                    job_id: '500123'
                    creator_user_name: example_value
                    run_as_user_name: example_value
                    settings:
                      name: Example Title
                      tasks:
    

# --- truncated at 32 KB (113 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/databricks/refs/heads/main/openapi/databricks-openapi.yml