Azure Databricks Jobs API

openapi: 3.2.0
info:
  title: Azure Databricks REST Clusters Jobs API
  description: Core REST API for managing Azure Databricks workspaces, clusters, jobs, and workspace objects programmatically. This specification covers the Clusters API (2.0), Jobs API (2.1), and Workspace API (2.0) endpoints available on Azure Databricks instances.
  version: 2.1.0
  contact:
    name: Azure Databricks Support
    url: https://learn.microsoft.com/answers/tags/166/azure-databricks
  license:
    name: Microsoft Azure Terms
    url: https://azure.microsoft.com/en-us/support/legal/
  x-apiReferenceDocumentation: https://docs.databricks.com/api/azure/workspace/introduction
servers:
- url: https://{databricks_instance}.azuredatabricks.net/api
  description: Azure Databricks workspace instance
  variables:
    databricks_instance:
      default: adb-1234567890123456.1
      description: The unique identifier for your Azure Databricks workspace instance. Found in the workspace URL.
security:
- BearerAuth: []
- AzureADToken: []
tags:
- name: Jobs
  description: Create and manage jobs to run notebooks, JARs, Spark submit, Python scripts, and pipeline tasks on Databricks clusters. Schedule recurring jobs, trigger runs, and monitor execution.
  externalDocs:
    description: Jobs API reference
    url: https://docs.databricks.com/api/azure/workspace/jobs
paths:
  /2.1/jobs/create:
    post:
      operationId: createJob
      summary: Azure Databricks Create a New Job
      description: Creates a new job with the provided settings. Returns the job_id of the newly created job.
      tags:
      - Jobs
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/JobSettings'
            examples:
              CreatejobRequestExample:
                summary: Default createJob request
                x-microcks-default: true
                value:
                  name: Example Title
                  tags: example_value
                  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
                  max_concurrent_runs: 10
                  schedule:
                    quartz_cron_expression: example_value
                    timezone_id: '500123'
                    pause_status: PAUSED
                  trigger:
                    file_arrival:
                      url: https://www.example.com
                      min_time_between_triggers_seconds: 10
                      wait_after_last_change_seconds: 10
                  continuous:
                    pause_status: PAUSED
                  git_source:
                    git_url: https://www.example.com
                    git_provider: gitHub
                    git_branch: example_value
                    git_tag: example_value
                    git_commit: 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
      responses:
        '200':
          description: Job created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  job_id:
                    type: integer
                    format: int64
                    description: 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'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalError'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /2.1/jobs/list:
    get:
      operationId: listJobs
      summary: Azure Databricks List All Jobs
      description: Retrieves a list of jobs defined in the workspace. Results are paginated with a default limit of 20 jobs per page.
      tags:
      - Jobs
      parameters:
      - name: limit
        in: query
        required: false
        description: Number of jobs to return. Default is 20 and maximum is 25.
        schema:
          type: integer
          default: 20
          maximum: 25
        example: 10
      - name: offset
        in: query
        required: false
        description: 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: Jobs list retrieved successfully
          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'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalError'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /2.1/jobs/get:
    get:
      operationId: getJob
      summary: Azure Databricks Get a Single Job
      description: Retrieves the details for a single job, including its settings and most recent run information.
      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: Job details retrieved successfully
          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
                      tags: example_value
                      tasks:
                      - {}
                      job_clusters:
                      - {}
                      notification_settings:
                        no_alert_for_skipped_runs: true
                        no_alert_for_canceled_runs: true
                      timeout_seconds: 10
                      max_concurrent_runs: 10
                      trigger:
                        file_arrival: {}
                      continuous:
                        pause_status: PAUSED
                      format: SINGLE_TASK
                      queue:
                        enabled: true
                      parameters:
                      - {}
                      run_as:
                        user_name: example_value
                        service_principal_name: example_value
                    created_time: 10
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalError'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /2.1/jobs/update:
    post:
      operationId: updateJob
      summary: Azure Databricks Partially Update a Job
      description: Adds, changes, or removes specific settings of an existing job. Use reset to overwrite all settings.
      tags:
      - Jobs
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - job_id
              properties:
                job_id:
                  type: integer
                  format: int64
                  description: The canonical identifier of the job to update
                new_settings:
                  $ref: '#/components/schemas/JobSettings'
                fields_to_remove:
                  type: array
                  items:
                    type: string
                  description: Fields to remove from the job settings. Removing nested fields is not supported except for task and job cluster configurations.
            examples:
              UpdatejobRequestExample:
                summary: Default updateJob request
                x-microcks-default: true
                value:
                  job_id: '500123'
                  new_settings:
                    name: Example Title
                    tags: example_value
                    tasks:
                    - {}
                    job_clusters:
                    - {}
                    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
                    max_concurrent_runs: 10
                    schedule:
                      quartz_cron_expression: example_value
                      timezone_id: '500123'
                      pause_status: PAUSED
                    trigger:
                      file_arrival:
                        url: https://www.example.com
                        min_time_between_triggers_seconds: 10
                        wait_after_last_change_seconds: 10
                    continuous:
                      pause_status: PAUSED
                    git_source:
                      git_url: https://www.example.com
                      git_provider: gitHub
                      git_branch: example_value
                      git_tag: example_value
                      git_commit: 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
                  fields_to_remove:
                  - example_value
      responses:
        '200':
          description: Job updated successfully
          content:
            application/json:
              schema:
                type: object
              examples:
                Updatejob200Example:
                  summary: Default updateJob 200 response
                  x-microcks-default: true
                  value: {}
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalError'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /2.1/jobs/reset:
    post:
      operationId: resetJob
      summary: Azure Databricks Overwrite All Job Settings
      description: Overwrites all settings for a specific job. Use update to change individual settings.
      tags:
      - Jobs
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - job_id
              - new_settings
              properties:
                job_id:
                  type: integer
                  format: int64
                  description: The canonical identifier of the job to reset
                new_settings:
                  $ref: '#/components/schemas/JobSettings'
            examples:
              ResetjobRequestExample:
                summary: Default resetJob request
                x-microcks-default: true
                value:
                  job_id: '500123'
                  new_settings:
                    name: Example Title
                    tags: example_value
                    tasks:
                    - {}
                    job_clusters:
                    - {}
                    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
                    max_concurrent_runs: 10
                    schedule:
                      quartz_cron_expression: example_value
                      timezone_id: '500123'
                      pause_status: PAUSED
                    trigger:
                      file_arrival:
                        url: https://www.example.com
                        min_time_between_triggers_seconds: 10
                        wait_after_last_change_seconds: 10
                    continuous:
                      pause_status: PAUSED
                    git_source:
                      git_url: https://www.example.com
                      git_provider: gitHub
                      git_branch: example_value
                      git_tag: example_value
                      git_commit: 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
      responses:
        '200':
          description: Job settings overwritten successfully
          content:
            application/json:
              schema:
                type: object
              examples:
                Resetjob200Example:
                  summary: Default resetJob 200 response
                  x-microcks-default: true
                  value: {}
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalError'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /2.1/jobs/delete:
    post:
      operationId: deleteJob
      summary: Azure Databricks Delete a Job
      description: Deletes a job and sends an email to the addresses specified in email_notifications. No action occurs if the job has already been removed.
      tags:
      - Jobs
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - job_id
              properties:
                job_id:
                  type: integer
                  format: int64
                  description: The canonical identifier of the job to delete
            examples:
              DeletejobRequestExample:
                summary: Default deleteJob request
                x-microcks-default: true
                value:
                  job_id: '500123'
      responses:
        '200':
          description: Job deleted successfully
          content:
            application/json:
              schema:
                type: object
              examples:
                Deletejob200Example:
                  summary: Default deleteJob 200 response
                  x-microcks-default: true
                  value: {}
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalError'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /2.1/jobs/run-now:
    post:
      operationId: runJobNow
      summary: Azure Databricks Trigger a New Job Run
      description: Runs the job now and returns the run_id of the triggered run. A job can have at most one active run at a time unless max_concurrent_runs is set.
      tags:
      - Jobs
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - job_id
              properties:
                job_id:
                  type: integer
                  format: int64
                  description: The ID of the job to trigger
                idempotency_token:
                  type: string
                  description: Optional token to guarantee idempotency of job run requests. Maximum length is 64 characters.
                  maxLength: 64
                notebook_params:
                  type: object
                  additionalProperties:
                    type: string
                  description: Map of parameter name-value pairs for notebook tasks.
                python_params:
                  type: array
                  items:
                    type: string
                  description: Parameters for Python tasks
                spark_submit_params:
                  type: array
                  items:
                    type: string
                  description: Parameters for Spark submit tasks
                jar_params:
                  type: array
                  items:
                    type: string
                  description: Parameters for JAR tasks
                pipeline_params:
                  type: object
                  properties:
                    full_refresh:
                      type: boolean
                      description: Whether to perform a full refresh of the pipeline
            examples:
              RunjobnowRequestExample:
                summary: Default runJobNow request
                x-microcks-default: true
                value:
                  job_id: '500123'
                  idempotency_token: example_value
                  notebook_params: example_value
                  python_params:
                  - example_value
                  spark_submit_params:
                  - example_value
                  jar_params:
                  - example_value
                  pipeline_params:
                    full_refresh: true
      responses:
        '200':
          description: Job run triggered successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  run_id:
                    type: integer
                    format: int64
                    description: Canonical identifier of the triggered run
                  number_in_job:
                    type: integer
                    format: int64
                    description: Sequence number of this run among all runs of the job
              examples:
                Runjobnow200Example:
                  summary: Default runJobNow 200 response
                  x-microcks-default: true
                  value:
                    run_id: '500123'
                    number_in_job: 10
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalError'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /2.1/jobs/runs/submit:
    post:
      operationId: submitRun
      summary: Azure Databricks Submit a One-time Run
      description: Submits a one-time run without creating a job. This endpoint allows you to submit a workload directly without defining a job. Returns the run_id of the submitted run.
      tags:
      - Jobs
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                run_name:
                  type: string
                  description: Optional name for the run
                tasks:
                  type: array
                  items:
                    $ref: '#/components/schemas/TaskSettings'
                  description: List of task specifications for the run
                timeout_seconds:
                  type: integer
                  format: int32
                  description: Timeout in seconds for the run. Default is no timeout.
                idempotency_token:
                  type: string
                  description: Idempotency token for the run submission
                  maxLength: 64
            examples:
              SubmitrunRequestExample:
                summary: Default submitRun request
                x-microcks-default: true
                value:
                  run_name: example_value
                  tasks:
                  - task_key: example_value
                    description: A sample description.
                    depends_on:
                    - {}
                    existing_cluster_id: '500123'
                    job_cluster_key: example_value
                    notebook_task:
                      notebook_path: example_value
                      base_parameters: example_value
                      source: WORKSPACE
                    spark_jar_task:
                      main_class_name: example_value
                      parameters: {}
                      jar_uri: example_value
                    spark_python_task:
                      python_file: example_value
                      parameters: {}
                      source: WORKSPACE
                    spark_submit_task:
                      parameters: {}
                    pipeline_task:
                      pipeline_id: '500123'
                      full_refresh: true
                    python_wheel_task:
                      package_name: example_value
                      entry_point: example_value
                      parameters: {}
                      named_parameters: example_value
                    sql_task:
                      warehouse_id: '500123'
                      query: {}
                      dashboard: {}
                      alert: {}
                      file: {}
                    dbt_task:
                      commands: {}
                      project_directory: example_value
                      schema: example_value
                      warehouse_id: '500123'
                      profiles_directory: example_value
                      catalog: example_value
                      source: WORKSPACE
                    run_if: ALL_SUCCESS
                    timeout_seconds: 10
                    max_retries: 10
                    min_retry_interval_millis: 10
                    retry_on_timeout: true
                    libraries:
                    - {}
                  timeout_seconds: 10
                  idempotency_token: example_value
      responses:
        '200':
          description: Run submitted successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  run_id:
                    type: integer
                    format: int64
                    description: Canonical identifier of the submitted run
              examples:
                Submitrun200Example:
                  summary: Default submitRun 200 response
                  x-microcks-default: true
                  value:
                    run_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/InternalError'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /2.1/jobs/runs/list:
    get:
      operationId: listJobRuns
      summary: Azure Databricks List Runs for a Job
      description: Lists runs in descending order by start time for a specific job or all jobs.
      tags:
      - Jobs
      parameters:
      - name: job_id
        in: query
        required: false
        description: Filter runs by the specified job ID
        schema:
          type: integer
          format: int64
        example: '500123'
      - name: active_only
        in: query
        required: false
        description: Show only active (running or pending) runs
        schema:
          type: boolean
          default: false
        example: true
      - name: completed_only
        in: query
        required: false
        description: Show only completed runs
        schema:
          type: boolean
          default: false
        example: true
      - name: offset
        in: query
        required: false
        description: Offset for pagination
        schema:
          type: integer
          default: 0
        example: 10
      - name: limit
        in: query
        required: false
        description: Number of runs to return. Maximum is 25.
        schema:
          type: integer
          default: 25
          maximum: 25
        example: 10
      - name: run_type
        in: query
        required: false
        description: Filter by run type
        schema:
          type: string
          enum:
          - JOB_RUN
          - WORKFLOW_RUN
          - SUBMIT_RUN
        example: JOB_RUN
      - name: expand_tasks
        in: query
        required: false
        description: Whether to include task details in the response
        schema:
          type: boolean
          default: false
        example: true
      - name: start_time_from
        in: query
        required: false
        description: Filter runs starting after this timestamp (epoch ms)
        schema:
          type: integer
          format: int64
        example: 10
      - name: start_time_to
        in: query
        required: false
        description: Filter runs starting before this timestamp (epoch ms)
        schema:
          type: integer
          format: int64
        example: 10
      responses:
        '200':
          description: Job runs retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  runs:
                    type: array
                    items:
                      $ref: '#/components/schemas/Run'
                  has_more:
                    type: boolean
                    description: Whether there are more runs to list
              examples:
                Listjobruns200Example:
                  summary: Default listJobRuns 200 response
                  x-microcks-default: true
                  value:
                    runs:
                    - run_id: '500123'
                      job_id: '500123'
                      run_name: example_value
                      creator_user_name: example_value
                      number_in_job: 10
                      tasks:
                      - {}
                      cluster_spec:
                        existing_cluster_id: '500123'
                      cluster_instance:
                        cluster_id: '500123'
                        spark_context_id: '500123'
                      start_time: 10
                      setup_duration: 10
                      execution_duration: 10
                      cleanup_duration: 10
                      end_time: 10
                      trigger: PERIODIC
                      run_type: JOB_RUN
                      attempt_number: 10
                      run_page_url: https://www.example.com
                      format: SINGLE_TASK
                    has_more: true
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':

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