openapi: 3.0.0
info:
  title: AI Service Actions jobs API
  version: 1.0.0
  contact:
    email: devel@keboola.com
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT
tags:
- name: jobs
paths:
  /api/v1/branches/{branchId}/workspaces/{workspaceId}/queries:
    post:
      summary: Submit query job
      operationId: ''
      tags:
      - jobs
      description: Create a new query job with SQL statements in the specified branch and workspace
      parameters:
      - name: branchId
        in: path
        required: true
        description: Branch ID
        schema:
          type: string
      - name: workspaceId
        in: path
        required: true
        description: Workspace ID
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/definitions/handlers.SubmitQueryJobRequest'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/definitions/handlers.SubmitJobResponse'
        '400':
          description: Bad request - invalid request body, missing parameters, or blocked SQL statement
          content:
            application/json:
              schema:
                $ref: '#/definitions/httperrors.ErrorResponse'
        '401':
          description: Unauthorized - project scope not found
          content:
            application/json:
              schema:
                $ref: '#/definitions/httperrors.ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/definitions/httperrors.ErrorResponse'
  /api/v1/queries/{queryJobId}:
    get:
      summary: Get job status
      operationId: ''
      tags:
      - jobs
      description: Retrieve the current status and statements of a query job by its ID
      parameters:
      - name: queryJobId
        in: path
        required: true
        description: Query job ID
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/definitions/handlers.JobStatusResponse'
        '400':
          description: Bad request - queryJobId is required
          content:
            application/json:
              schema:
                $ref: '#/definitions/httperrors.ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/definitions/httperrors.ErrorResponse'
  /api/v1/queries/{queryJobId}/cancel:
    post:
      summary: Cancel job
      operationId: ''
      tags:
      - jobs
      description: Cancel a running query job by its ID. The job will be marked for cancellation and stopped as soon as possible.
      parameters:
      - name: queryJobId
        in: path
        required: true
        description: Query job ID
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/definitions/handlers.CancelQueryJobRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/definitions/handlers.CancelQueryJobResponse'
        '400':
          description: Bad request - invalid request body, missing queryJobId, or job already in terminal state
          content:
            application/json:
              schema:
                $ref: '#/definitions/httperrors.ErrorResponse'
        '401':
          description: Unauthorized - project scope not found
          content:
            application/json:
              schema:
                $ref: '#/definitions/httperrors.ErrorResponse'
        '404':
          description: Not found - job not found
          content:
            application/json:
              schema:
                $ref: '#/definitions/httperrors.ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/definitions/httperrors.ErrorResponse'
  /api/v1/queries/{queryJobId}/{statementId}/export:
    get:
      summary: Export job results as CSV or Parquet
      operationId: ''
      tags:
      - jobs
      description: Export the results of a specific statement within a query job as a downloadable file (CSV or Parquet). Creates a temporary table from query results, exports it to Storage API, and returns the content to the client.
      parameters:
      - name: queryJobId
        in: path
        required: true
        description: Query job ID
        schema:
          type: string
      - name: statementId
        in: path
        required: true
        description: Statement ID
        schema:
          type: string
      - name: fileType
        in: query
        required: true
        description: 'Export format: csv or parquet'
        schema:
          type: string
          enum:
          - csv
          - parquet
      - name: gzip
        in: query
        required: false
        description: Enable gzip compression for the exported file
        schema:
          type: boolean
      responses:
        '200':
          description: File download (CSV or Parquet)
          content:
            application/json:
              schema:
                type: file
        '400':
          description: Bad request - invalid format, queryJobId or statementId is required, or statement not completed
          content:
            application/json:
              schema:
                $ref: '#/definitions/httperrors.ErrorResponse'
        '404':
          description: Not found - job or statement not found
          content:
            application/json:
              schema:
                $ref: '#/definitions/httperrors.ErrorResponse'
        '413':
          description: Payload Too Large - export exceeds maximum allowed size
          content:
            application/json:
              schema:
                $ref: '#/definitions/httperrors.ErrorResponse'
        '500':
          description: Internal server error - failed to create table, export, or download file
          content:
            application/json:
              schema:
                $ref: '#/definitions/httperrors.ErrorResponse'
  /api/v1/queries/{queryJobId}/{statementId}/profile:
    get:
      summary: Get statement profile
      operationId: ''
      tags:
      - jobs
      description: Get the profile of a specific statement within a query job.
      parameters:
      - name: queryJobId
        in: path
        required: true
        description: Query job ID
        schema:
          type: string
      - name: statementId
        in: path
        required: true
        description: Statement ID
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/definitions/handlers.Profile'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/definitions/httperrors.ErrorResponse'
  /api/v1/queries/{queryJobId}/{statementId}/results:
    get:
      summary: Get job results
      operationId: ''
      tags:
      - jobs
      description: Retrieve the results of a specific statement within a query job. Returns data, rows affected count, and status information with pagination support.
      parameters:
      - name: queryJobId
        in: path
        required: true
        description: Query job ID
        schema:
          type: string
      - name: statementId
        in: path
        required: true
        description: Statement ID
        schema:
          type: string
      - name: offset
        in: query
        required: false
        description: Offset for pagination
        schema:
          type: integer
      - name: pageSize
        in: query
        required: false
        description: Page size for pagination
        schema:
          type: integer
      responses:
        '200':
          description: Regular JSON response
          content:
            application/json:
              schema:
                $ref: '#/definitions/handlers.ResultResponse'
        '400':
          description: Bad request - queryJobId or statementId is required
          content:
            application/json:
              schema:
                $ref: '#/definitions/httperrors.ErrorResponse'
        '404':
          description: Not found - job or statement not found
          content:
            application/json:
              schema:
                $ref: '#/definitions/httperrors.ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/definitions/httperrors.ErrorResponse'
  /api/v1/queries/{queryJobId}/{statementId}/results/stream:
    get:
      summary: Stream job results
      operationId: ''
      tags:
      - jobs
      description: Stream the results of a specific statement within a query job using HTTP/2 chunked transfer encoding. Returns data as NDJSON format for efficient streaming of large result sets.
      parameters:
      - name: queryJobId
        in: path
        required: true
        description: Query job ID
        schema:
          type: string
      - name: statementId
        in: path
        required: true
        description: Statement ID
        schema:
          type: string
      responses:
        '200':
          description: Streaming NDJSON response
          content:
            application/json:
              schema:
                type: string
        '400':
          description: Bad request - queryJobId or statementId is required
          content:
            application/json:
              schema:
                $ref: '#/definitions/httperrors.ErrorResponse'
        '404':
          description: Not found - job or statement not found
          content:
            application/json:
              schema:
                $ref: '#/definitions/httperrors.ErrorResponse'
        '426':
          description: Upgrade Required - HTTP/2 required for streaming
          content:
            application/json:
              schema:
                $ref: '#/definitions/httperrors.ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/definitions/httperrors.ErrorResponse'
  /jobs:
    get:
      summary: List jobs
      deprecated: true
      description: 'List jobs and filter them by various criteria.


        This endpoint is DEPRECATED. Use `/search/jobs` instead.

        '
      tags:
      - jobs
      parameters:
      - in: query
        name: id
        description: Search jobs by *id*. You can set multiple values.
        required: false
        schema:
          type: array
          items:
            type: string
        examples:
          oneId:
            summary: Single id
            value:
            - '123'
          multipleIds:
            summary: Multiple ids
            value:
            - '123'
            - '456'
            - '789'
      - in: query
        name: runId
        description: Search jobs by *runId*. You can set multiple values.
        required: false
        schema:
          type: array
          items:
            type: string
        examples:
          oneId:
            summary: Single runId
            value:
            - '123'
          multipleIds:
            summary: Multiple runIds
            value:
            - '123'
            - '456'
            - '789'
      - in: query
        name: branchId
        description: 'Search jobs by *branchId*. You can set multiple values.


          Set **branchId[]=null** to get just jobs belonging to the **main** branch.

          '
        required: false
        schema:
          type: array
          items:
            type: string
        examples:
          mainBranch:
            summary: Jobs ran on the main branch
            value:
            - 'null'
          oneId:
            summary: Jobs ran on a branch
            value:
            - '123'
          multipleIds:
            summary: Jobs ran on multiple branches
            value:
            - '123'
            - '456'
            - '789'
      - in: query
        name: tokenId
        description: Search jobs by *tokenId*. You can set multiple values.
        required: false
        schema:
          type: array
          items:
            type: string
        examples:
          oneId:
            summary: Single tokenId
            value:
            - '123'
          multipleIds:
            summary: Multiple tokenIds
            value:
            - '123'
            - '456'
            - '789'
      - in: query
        name: tokenDescription
        description: Search jobs by *tokenDescription*. You can set multiple values.
        required: false
        schema:
          type: array
          items:
            type: string
        examples:
          oneId:
            summary: Single tokenDescription
            value:
            - My token
          multipleIds:
            summary: Multiple tokenDescriptions
            value:
            - My token
            - Your token
            - Omni token
      - in: query
        name: component
        description: Search jobs by *component id*. You can set multiple values.
        required: false
        schema:
          type: array
          items:
            type: string
        examples:
          oneId:
            summary: Single component
            value:
            - keboola.ex-db-snowflake
          multipleIds:
            summary: Multiple components
            value:
            - keboola.ex-google-drive
            - keboola.wr-db-snowflake
      - in: query
        name: config
        description: Search jobs by *configuration id*. You can set multiple values.
        required: false
        schema:
          type: array
          items:
            type: string
        examples:
          oneId:
            summary: Single configuration
            value:
            - '123'
          multipleIds:
            summary: Multiple configurations
            value:
            - '123'
            - '456'
            - '789'
      - in: query
        name: configRowIds
        description: Search jobs by *configuration row id*. Each job can have multiple configRowIds or none. You can search for multiple values and all jobs containing at least one of the specified configRowIds will be returned in that case.
        required: false
        schema:
          type: array
          items:
            type: string
        examples:
          oneId:
            summary: Single configRowId
            value:
            - '123'
          multipleIds:
            summary: Multiple configRowIds
            value:
            - '123'
            - '456'
            - '789'
      - in: query
        name: mode
        description: Filter jobs by *mode*. You can use either *run* or *debug* values.
        required: false
        schema:
          type: array
          items:
            type: string
            enum:
            - run
            - debug
        examples:
          oneId:
            summary: Single mode
            value:
            - run
          multipleIds:
            summary: Multiple modes
            value:
            - run
            - debug
      - in: query
        name: status
        description: Search jobs by *status*. You can set multiple values.
        required: false
        schema:
          type: array
          items:
            $ref: '#/components/schemas/JobStatus'
        examples:
          oneId:
            summary: Jobs with a status
            value:
            - created
          multipleIds:
            summary: Jobs with either of statuses
            value:
            - waiting
            - processing
            - terminated
      - in: query
        name: type
        description: Filter jobs by job *type*.
        required: false
        schema:
          type: string
          enum:
          - standard
          - container
          - phaseContainer
          - orchestrationContainer
          - retryContainer
        examples:
          standardJobs:
            summary: Standard Jobs
            value: standard
      - in: query
        name: componentProps
        description: Filter jobs by component properties. Only "type" is currently supported. It lists jobs of components with the given type, having a configuration in the project.
        required: false
        style: deepObject
        explode: true
        schema:
          type: object
          properties:
            type:
              type: string
        examples:
          oneType:
            summary: List only Extractors
            value:
              type: extractors
      - in: query
        name: createdTimeFrom
        description: Jobs that were created after *createdTimeFrom*. [Supported date and time formats](https://www.php.net/manual/en/datetime.formats.php)
        required: false
        schema:
          type: string
        examples:
          lastWeek:
            summary: Jobs created in the last week
            value: -1 week
          last8Hours:
            summary: Jobs created in last 8 hours
            value: -8 hours
          exactDate:
            summary: Jobs created after 2021-01-01
            value: '2021-01-01'
      - in: query
        name: createdTimeTo
        description: Jobs that were created before *createdTimeTo*. [Supported date and time formats](https://www.php.net/manual/en/datetime.formats.php)
        required: false
        schema:
          type: string
        examples:
          lastWeek:
            summary: Jobs created before today
            value: today
          last8Hours:
            summary: Jobs created before last monday
            value: last monday
          exactDate:
            summary: Jobs created before 2021-01-01
            value: '2021-01-01'
      - in: query
        name: startTimeFrom
        description: Jobs that started after *startTimeFrom*. [Supported date and time formats](https://www.php.net/manual/en/datetime.formats.php)
        required: false
        schema:
          type: string
        examples:
          lastWeek:
            summary: Jobs started in the last week
            value: -1 week
          last8Hours:
            summary: Jobs started in last 8 hours
            value: -8 hours
          exactDate:
            summary: Jobs started after 2021-01-01
            value: '2021-01-01'
      - in: query
        name: startTimeTo
        description: Jobs that started before *startTimeTo*. [Supported date and time formats](https://www.php.net/manual/en/datetime.formats.php)
        required: false
        schema:
          type: string
        examples:
          lastWeek:
            summary: Jobs started before today
            value: today
          last8Hours:
            summary: Jobs started before last monday
            value: last monday
          exactDate:
            summary: Jobs started before 2021-01-01
            value: '2021-01-01'
      - in: query
        name: endTimeFrom
        description: Jobs that ended after *endTimeFrom*. [Supported date and time formats](https://www.php.net/manual/en/datetime.formats.php)
        required: false
        schema:
          type: string
        examples:
          lastWeek:
            summary: Jobs ended in the last week
            value: -1 week
          last8Hours:
            summary: Jobs ended in last 8 hours
            value: -8 hours
          exactDate:
            summary: Jobs ended after 2021-01-01
            value: '2021-01-01'
      - in: query
        name: endTimeTo
        description: Jobs that ended before *endTimeTo*. [Supported date and time formats](https://www.php.net/manual/en/datetime.formats.php)
        required: false
        schema:
          type: string
        examples:
          lastWeek:
            summary: Jobs ended before today
            value: today
          last8Hours:
            summary: Jobs ended before last monday
            value: last monday
          exactDate:
            summary: Jobs ended before 2021-01-01
            value: '2021-01-01'
      - in: query
        name: durationSecondsFrom
        description: Jobs that were running for *durationSecondsFrom* seconds or more.
        required: false
        schema:
          type: number
        examples:
          moreThanHour:
            summary: More than 1 hour
            value: 3600
      - in: query
        name: durationSecondsTo
        description: Jobs that were running less than *durationSecondsTo* seconds.
        required: false
        schema:
          type: number
        examples:
          lessThanDay:
            summary: Less than a day
            value: 86400
      - in: query
        name: offset
        description: Page offset
        required: false
        schema:
          type: integer
          default: 0
        example: 50
      - in: query
        name: limit
        description: Maximum limit of items per page
        required: false
        schema:
          type: integer
          default: 100
        example: 1000
      - in: query
        name: sortBy
        description: Sort the jobs by specified attribute.
        required: false
        schema:
          type: string
          enum:
          - id
          - runId
          - branchId
          - projectId
          - projectName
          - tokenId
          - tokenDescription
          - componentId
          - configId
          - configRowIds
          - tag
          - mode
          - status
          - startTime
          - createdTime
          - endTime
          - durationSeconds
          - result
          default: id
        example: runId
      - in: query
        name: sortOrder
        description: Order of the sorting. Default is *desc*, newest jobs are displayed at the top.
        required: false
        schema:
          type: string
          enum:
          - asc
          - desc
          default: desc
        example: asc
      responses:
        '200':
          description: Success response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Job'
        default:
          description: Error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    post:
      summary: Create a job
      operationId: createJob
      tags:
      - jobs
      description: 'Create a new Job

        '
      parameters:
      - in: header
        name: X-KBC-RunId
        schema:
          type: string
          example: 1234567890
        description: Run ID of parent job (see the description of runId property in Job schema)
      requestBody:
        description: '## Basic Job

          Use "run" **mode** to create a new job of a component specified by **component** with configuration defined either by **config** and optionally **configRow** or provide the whole configuration for the component in the **configData** attribute. Use "forceRun" **mode** to create a new job of a disabled configuration.


          ## Job of specific component image tag

          Specify the component image tag in the **tag** attribute.


          ## Debug job

          This API call has the same body attributes as the Run call, except the **mode** attribute is set to "debug" (default is "run"). It creates a job that prepares the data folder including the serialized configuration files. Then it compresses the data folder and uploads it to your project''s Files in Storage. This way you will get a snapshot of what the data folder looked like before the component started. If processors are used, a snapshot of the data folder is created before each processor. After the entire component finishes, another snapshot is made.

          For example, if you run component a with processor b and c in the after section, you will receive:

          - stage_0 file with contents of the data folder before component a was run

          - stage_1 file with contents of the data folder before processor b was run

          - stage_2 file with contents of the data folder before processor c was run

          - stage_output file with contents of the data folder before output mapping was about to be performed (after c finished).


          If configuration rows are used, then the above is repeated for each configuration row. If the job finishes with and error, only the stages before the error are uploaded.


          This API call does not upload any tables or files to Storage. I.e. when the component finishes, its output is discarded and the output mapping to storage is **not performed**. This makes this API call generally very safe to call, because it cannot break the KBC project in any way. However keep in mind, that if the component has any outside side effects, these will get executed. This applies typically to writers which will write the data into the external system even with this debug API call.


          Note that the snapshot archive will contain all files in the data folder including any temporary files produced be the component. The snapshot will not contain the output state.json file. This is because the snapshot is made before a component is run where the out state of the previous component is not available any more. Also note that all encrypted values are removed from the configuration file and there is no way to retrieve them. It is also advisable to run this command with limited input mapping so that you don''t end up with gigabyte size archives.

          '
        content:
          application/json:
            schema:
              type: object
              required:
              - component
              properties:
                component:
                  type: string
                mode:
                  type: string
                  enum:
                  - run
                  - debug
                  - forceRun
                  default: run
                config:
                  type: string
                configRowIds:
                  type: array
                  items:
                    type: string
                configData:
                  type: object
                tag:
                  type: string
                branchId:
                  type: string
                variableValuesId:
                  type: string
                variableValuesData:
                  type: object
                  required:
                  - values
                  properties:
                    values:
                      type: array
                      items:
                        type: object
                        required:
                        - name
                        - value
                        properties:
                          name:
                            type: string
                          value:
                            type: string
                backend:
                  type: object
                  required:
                  - type
                  properties:
                    type:
                      type: string
                      enum:
                      - xsmall
                      - small
                      - medium
                      - large
                    context:
                      type: string
                executor:
                  type: string
                  enum:
                  - dind
                  - k8sContainers
                delayedStartTime:
                  type: string
                  format: date-time
                  description: Delayed start time - the earliest time when the job can be started. Cannot be used together with "delay".
                  example: '2025-06-21T09:12:33.001Z'
                delay:
                  type: integer
                  minimum: 0
                  description: Delay in seconds before the job can be started. Cannot be used together with "delayedStartTime".
                  example: 3600
            examples:
              Job with configRows:
                value:
                  component: keboola.ex-db-snowflake
                  mode: run
                  config: '123456789'
                  configRowIds:
                  - '12345'
                  - '67890'
              Job with configData:
                value:
                  component: keboola.ex-db-snowflake
                  mode: run
                  configData:
                    parameters:
                      foo: bar
                      baz: mek
              Job with image tag:
                value:
                  component: keboola.ex-db-snowflake
                  mode: run
                  config: '123456789'
                  tag: 1.2.3
              Job in debug mode:
                value:
                  component: keboola.ex-db-snowflake
                  mode: debug
                  config: '123456789'
              Job in dev branch:
                value:
                  component: keboola.ex-db-snowflake
                  mode: debug
                  config: '123456789'
                  branchId: '456789'
              Job with pre-defined variable Values:
                value:
                  component: keboola.ex-db-snowflake
                  mode: debug
                  config: '123456789'
                  variableValuesId: '456789'
              Job with inline variable values:
                value:
                  component: keboola.ex-db-snowflake
                  mode: debug
                  config: '123456789'
                  variableValuesData:
                    values:
                    - name: someVariable
                      value: someValue
              Job with customized backend:
                value:
                  component: keboola.ex-db-snowflake
                  mode: run
                  config: '123456789'
                  backend:
                    type: medium
              Job with customized backend context:
                value:
                  component: keboola.ex-db-snowflake
                  mode: run
                  config: '123456789'
                  backend:
                    context: 123_extractor
      responses:
        '201':
          description: Job created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Job'
        default:
          description: Error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /jobs/{jobId}:
    get:
      summary: Get job detail
      operationId: getJob
      tags:
      - jobs
      description: 'Get details of specified job

        '
      parameters:
      - in: path
        name: jobId
        description: Job ID
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Job'
        default:
          description: Error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /jobs/{jobId}/kill:
    post:
      summary: Set job for termination
      operationId: killJob
      tags:
      - jobs
      description: 'Sets the job desiredStatus to **terminating**. The daemon will pick such a job and depending on its current status, it will either cancell it, if the job was still in the **created** or **waiting** state, or if the job already entered **processing** state, it will be **terminated**.

        '
      parameters:
      - in: path
        name: jobId
        description: Job ID
        required: true
        schema:
          type: string
      responses:
        '202':
          description: Success response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Job'
        default:
          description: Error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /jobs/{jobId}/open-api-lineage:
    get:
      summary: Get job OpenLineage data
      operationId: getJobOpenApiLineage
      tags:
      - jobs
      description: 'Retreive details about executed job as events list in OpenLineage format. For orchestration, container and phase jobs, events from child jobs are also included.

        '
      parameters:
      - in: path
        name: jobId
        description: Job ID
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OpenLineageEventList'
        default:
          description: Error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /search/jobs:
    get:
      summary: Search jobs
      description: 'Search jobs and filter them by various criteria.


        Search endpoints result are eventually consistent as it does not return data directly from internal storage but

        from a search index. This means that results are not guaranteed to be 100% consistent. There is always slight

        delay before created/updated job data is propagated to the search.

        '
      tags:
      - jobs
      parameters:
      - in: query
        name: id
        description: Search jobs by *id*. You can set multiple values.
        required: false
        schema:
          type: array
          items:
            type: string
        examples:
          oneId:
            summary: Single id
            value:
            - '123'
          multipleIds:
            summary: Multiple ids
            value:
            - '123'
            - '456'
            - '789'
      - in: query
        name: runId
        description: Search jobs by *runId*. You can set multiple values.
        required: false
        schema:
          type: array
          items:
            type: string
        examples:
          oneId:
            summary: Single runId
            value:
            - '123'
          multipleIds:
            summary: Multiple runIds
            value:
            - '123'
            - '456'
            - '789'
      - in: query
        name: branchId
        description: 'Search jobs by *branchId*. You can set multiple values.


          Set **branchId[]=null** to get just jobs belonging to the **main** branch.

          '
        required: false
        schema:
          type: array
          items:
            type: string
        examples:
          mainBranch:
            summary: Jobs ran on the main branch
            value:
            - 'null'
          oneId:
            summary: Jobs ran on a branch
            value:
            - '123'
          multipleIds:
            summary: Jobs ran on multiple branches
            value:
            - '123'
            - '456'
            - '789'
      - in: query
        name: tokenId
        description: Search jobs by *tokenId*. You can set multiple values.
        required: false
        schema:
          type: array
          items:
            type: string
        examples:
          oneId:
            summary: Single tokenId
            value:
            - '123'
          multipleIds:
            summary: Multiple tokenIds
            value:
            - '123'
            - '456'
            - '789'
      - in: query
        name: tokenDescription
        description: Search jobs by *tokenDescription*. You can set multiple values.
        required: false
        schema:
          type: array
          items:
            type: string
        examples:
          oneId:
            summary: Single tokenDescription
            value:
            - My token
          multipleIds:
            summary: Multiple tokenDescriptions
            value:
            - My token
            - Your token
            - Omni token
      - in: query
        name: componentId
        description: Search jobs by *component id*. You can set multiple values.
        required: false
        schema:
          type: array
          items:
            type: string
        examples:
          oneId:
            summary: Single component
            value:
            - keboola.ex-db-snowflake
          multipleIds:
            summary: Multiple components
            value:
            - keboola.ex-google-drive
            - keboola.wr-db-snowflake
      - in: query
        name: component
        description: Alias to `componentId` filter.
        deprecated: true
        required: false
        schema:
          type: array
          items:
            type: string
      - in: query
        name: configId
        description: Search jobs by *configuration id*. You can set multiple values.
        required: false
        schema:
          type: array
          items:
            type: string
        examples:
          oneId:
            summary: Single configuration
            value:
            - '123'
          multipleIds:
            summary: Multiple configurations
            value:
            - '123'
            - '456'
            - '789'
      - in: query
        name: config
        description: Alias to `configId` filter.
        deprecated: true
        required: false
        schema:
          type: array
          items:
            type: string
      - in: query
        name: configRowIds
        description: Search jobs by *configuration row id*. Each job can have multiple configRowIds or none. You can search for multiple values and all jobs containing at least one of the specified configRowIds will be returned in that case.
        required: false
        schema:
          type: array
          items:
            type: string
        examples:
          oneId:
            summary: Single configRowId
            value:
            - '123'
          multipleIds:
            summary: Multiple configRowIds
            value:
            - '123'
            - '456'
            - '789'
      - in: query
        name: mode
        description: Filter jobs by *mode*. You can use either *run* or *debug* values.
        required: false
        schema:
          type: array
          items:
            type: string
            enum:
            - run
            - debug
        examples:
          oneId:
            summary: Single mode
            value:
            - run
          multipleIds:
            summary: Multiple modes
            value:
            - run
            - debug
      - in: query
        name: status
        description: Search jobs by *status*. You can set multiple values.
        required: false
        schema:
          type: array
          items:
            $ref: '#/components/schemas/JobStatus'
        examples:
          oneId:
            summary: Jobs with a status
            value:
            - created
          multipleIds:
            summary: Jobs with either of statuses
            value:
            - waiting
            - processing
            - terminated
      - in: query
        name: type
        description: Filter jobs by job *type*.
        required: false
        schema:
          type: string
          enum:
          - standard
          - container
          - phaseContainer
          - orchestrationContainer
          - retryContainer
        examples:
          standardJobs:
            summary: Standard Jobs
            value: standard
      - in: query
        name: componentProps
        description: Filter jobs by component properties. Only "type" is currently supported. It lists jobs of components with the given type, having a configuration in the project.
        required: false
        style: deepObject
        explode: true
        schema:
          type: object
          properties:
            type:
              type: string
        examples:
          oneType:
            summary: List only Extractors
            value:
              type: extractors
      - in: query
        name: createdTimeFrom
        description: Jobs that were created after *createdTimeFrom*. [Supported date and time formats](https://www.php.net/manual/en/datetime.formats.php)
        required: false
        schema:
          type: string
        examples:
          lastWeek:
            summary: Jobs created in the last week
            value: -1 week
          last8Hours:
            summary: Jobs created in last 8 hours
            value: -8 hours
          exactDate:
            summary: Jobs created after 2021-01-01
            value: '2021-01-01'
      - in: query
        name: createdTimeTo
        description: Jobs that were created before *createdTimeTo*. [Supported date and time formats](https://www.php.net/manual/en/datetime.formats.php)
        required: false
        schema:
          type: string
        examples:
          lastWeek:
            summary: Jobs created before today
            value: today
          last8Hours:
            summary: Jobs created before last monday
            value: last monday
          exactDate:
            summary: Jobs created before 2021-01-01
            value: '2021-01-01'
      - in: query
        name: startTimeFrom
        description: Jobs that started after *startTimeFrom*. [Supported date and time formats](https://www.php.net/manual/en/datetime.formats.php)
        required: false
        schema:
          type: string
        examples:
          lastWeek:
            summary: Jobs started in the last week
            value: -1 week
          last8Hours:
            summary: Jobs started in last 8 hours
            value: -8 hours
          exactDate:
            summary: Jobs started after 2021-01-01
            value: '2021-01-01'
      - in: query
        name: startTimeTo
        description: Jobs that started before *startTimeTo*. [Supported date and time formats](https://www.php.net/manual/en/datetime.formats.php)
        required: false
        schema:
          type: string
        examples:
          lastWeek:
            summary: Jobs started before today
            value: today
          last8Hours:
            summary: Jobs started before last monday
            value: last monday
          exactDate:
            summary: Jobs started before 2021-01-01
            value: '2021-01-01'
      - in: query
        name: endTimeFrom
        description: Jobs that ended after *endTimeFrom*. [Supported date and time formats](https://www.php.net/manual/en/datetime.formats.php)
        required: false
        schema:
          type: string
        examples:
          lastWeek:
            summary: Jobs ended in the last week
            value: -1 week
          last8Hours:
            summary: Jobs ended in last 8 hours
            value: -8 hours
          exactDate:
            summary: Jobs ended after 2021-01-01
            value: '2021-01-01'
      - in: query
        name: endTimeTo
        description: Jobs that ended before *endTimeTo*. [Supported date and time formats](https://www.php.net/manual/en/datetime.formats.php)
        required: false
        schema:
          type: string
        examples:
          lastWeek:
            summary: Jobs ended before today
            value: today
          last8Hours:
            summary: Jobs ended before last monday
            value: last monday
          exactDate:
            summary: Jobs ended before 2021-01-01
            value: '2021-01-01'
      - in: query
        name: durationSecondsFrom
        description: Jobs that were running for *durationSecondsFrom* seconds or more.
        required: false
        schema:
          type: number
        examples:
          moreThanHour:
            summary: More than 1 hour
            value: 3600
      - in: query
        name: durationSecondsTo
        description: Jobs that were running less than *durationSecondsTo* seconds.
        required: false
        schema:
          type: number
        examples:
          lessThanDay:
            summary: Less than a day
            value: 86400
      - in: query
        name: offset
        description: Page offset
        required: false
        schema:
          type: integer
          default: 0
        example: 50
      - in: query
        name: limit
        description: Maximum limit of items per page
        required: false
        schema:
          type: integer
          default: 100
        example: 1000
      - in: query
        name: sortBy
        description: Sort the jobs by specified attribute.
        required: false
        schema:
          type: string
          enum:
          - id
          - runId
          - projectId
          - branchId
          - componentId
          - configId
          - tokenDescription
          - status
          - createdTime
          - updatedTime
          - startTime
          - endTime
          - durationSeconds
          default: id
        example: runId
      - in: query
        name: sortOrder
        description: Order of the sorting. Default is *desc*, newest jobs are displayed at the top.
        required: false
        schema:
          type: string
          enum:
          - asc
          - desc
          default: desc
        example: asc
      responses:
        '200':
          description: Success response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Job'
        default:
          description: Error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /search/grouped-jobs:
    get:
      summary: Search grouped jobs
      description: 'Search for jobs by their attributes and aggregating them into specified groups.


        Search endpoints result are eventually consistent as it does not return data directly from internal storage but

        from a search index. This means that results are not guaranteed to be 100% consistent. There is always slight

        delay before created/updated job data is propagated to the search.

        '
      tags:
      - jobs
      parameters:
      - in: query
        name: groupBy
        required: true
        schema:
          type: array
          items:
            type: string
            enum:
            - projectId
            - branchId
            - componentId
            - configId
        description: Specifies the fields to group jobs by.
      - in: query
        name: jobsPerGroup
        schema:
          type: integer
          minimum: 1
          default: 5
        description: Number of jobs per group.
      - in: query
        name: sortBy
        schema:
          type: string
          enum:
          - id
          - runId
          - projectId
          - branchId
          - componentId
          - configId
          - tokenDescription
          - status
          - createdTime
          - updatedTime
          - startTime
          - endTime
          - durationSeconds
          default: id
        description: Field to sort the results by.
      - in: query
        name: sortOrder
        schema:
          type: string
          enum:
          - asc
          - desc
          default: asc
        description: Order of sorting (asc or desc).
      - in: query
        name: limit
        schema:
          type: integer
          minimum: 1
          default: 100
        description: Maximum number of results to return.
      - in: query
        name: id
        schema:
          type: array
          items:
            type: integer
            minimum: 1
        description: Filter by specific job IDs.
      - in: query
        name: runId
        schema:
          type: array
          items:
            type: string
            minLength: 1
        description: Filter jobs by run IDs.
      - in: query
        name: branchId
        schema:
          type: array
          items:
            type: string
            minLength: 1
        description: Filter jobs by branch IDs.
      - in: query
        name: configId
        schema:
          type: array
          items:
            type: string
            minLength: 1
        description: Filter jobs by configuration IDs.
      - in: query
        name: config
        deprecated: true
        schema:
          type: array
          items:
            type: string
            minLength: 1
        description: Alias to `configId` filter.
      - in: query
        name: configRowIds
        schema:
          type: array
          items:
            type: string
            minLength: 1
        description: Filter jobs by configuration row IDs.
      - in: query
        name: projectId
        schema:
          type: array
          items:
            type: string
            minLength: 1
        description: Filter jobs by project IDs.
      - in: query
        name: tokenId
        schema:
          type: array
          items:
            type: string
            minLength: 1
        description: Filter jobs by token IDs.
      - in: query
        name: tokenDescription
        schema:
          type: array
          items:
            type: string
            minLength: 1
        description: Filter jobs by token descriptions.
      - in: query
        name: componentId
        schema:
          type: array
          items:
            type: string
            minLength: 1
        description: Filter jobs by component names.
      - in: query
        name: component
        deprecated: true
        schema:
          type: array
          items:
            type: string
            minLength: 1
        description: Alias to `componentId` filter.
      - in: query
        name: status
        schema:
          type: array
          items:
            type: string
            minLength: 1
        description: Filter jobs by status.
      - in: query
        name: desiredStatus
        schema:
          type: array
          items:
            type: string
            minLength: 1
        description: Filter jobs by desired status.
      - in: query
        name: mode
        schema:
          type: array
          items:
            type: string
            minLength: 1
        description: Filter jobs by mode.
      - in: query
        name: tag
        schema:
          type: array
          items:
            type: string
            minLength: 1
        description: Filter jobs by tags.
      - in: query
        name: startTimeFrom
        schema:
          type: string
          format: date-time
        description: Filter jobs that started from this timestamp onwards.
      - in: query
        name: startTimeTo
        schema:
          type: string
          format: date-time
        description: Filter jobs that started up to this timestamp.
      - in: query
        name: createdTimeFrom
        schema:
          type: string
          format: date-time
        description: Filter jobs created from this timestamp onwards.
      - in: query
        name: createdTimeTo
        schema:
          type: string
          format: date-time
        description: Filter jobs created up to this timestamp.
      - in: query
        name: endTimeFrom
        schema:
          type: string
          format: date-time
        description: Filter jobs that ended from this timestamp onwards.
      - in: query
        name: endTimeTo
        schema:
          type: string
          format: date-time
        description: Filter jobs that ended up to this timestamp.
      - in: query
        name: durationSecondsFrom
        schema:
          type: integer
          minimum: 0
        description: Filter jobs with a duration longer than this number of seconds.
      - in: query
        name: durationSecondsTo
        schema:
          type: integer
          minimum: 0
        description: Filter jobs with a duration up to this number of seconds.
      - in: query
        name: variableValuesId
        schema:
          type: array
          items:
            type: string
            minLength: 1
        description: Filter jobs by variable values IDs.
      - in: query
        name: parentRunId
        schema:
          type: array
          items:
            type: string
            minLength: 1
        description: Filter jobs by parent run IDs.
      - in: query
        name: type
        schema:
          type: array
          items:
            type: string
            minLength: 1
        description: Filter jobs by type.
      - in: query
        name: componentProps
        schema:
          type: object
          properties:
            type:
              type: string
        description: Filter jobs by specific component properties as key-value pairs.
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    group:
                      type: object
                      additionalProperties:
                        type: string
                    jobs:
                      type: array
                      items:
                        $ref: '#/components/schemas/Job'
        default:
          description: Error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    OpenLineageEvent:
      type: object
      oneOf:
      - $ref: '#/components/schemas/OpenLineageStartEvent'
      - $ref: '#/components/schemas/OpenLineageCompleteEvent'
    OpenLineageEventList:
      type: array
      minItems: 1
      description: OpenLineage event list
      items:
        $ref: '#/components/schemas/OpenLineageEvent'
    Error:
      type: object
      required:
      - error
      - code
      - status
      properties:
        error:
          type: string
          example: The value foobar is invalid
        code:
          type: integer
          example: 400
        status:
          type: string
          enum:
          - error
        exceptionId:
          type: string
          example: job-runner-1234567890
    Job:
      type: object
      required:
      - id
      - runId
      - project
      - token
      - status
      - mode
      - component
      - createdTime
      - isFinished
      - url
      properties:
        id:
          type: string
          example: '123456789'
        runId:
          type: string
          example: '123456790.123456789'
          description: 'Run ID is same as Job ID, unless the job is a child job. A child

            job is created by providing the parent Run ID in the X-KBC-RunId

            parameter. The runId of a child job contains the parent runId and

            the child job ID separated by dot. The nesting depth is not limited.

            A parent-child job relationship means that e.g. when a parent job is terminated

            it''s child jobs are terminated too. The parent-child job relationship

            does not mean that the parent will wait for it''s children to finish.

            '
        branchId:
          type: string
          example: '123456789'
          description: 'Jobs from the main branch will have branchId = null

            '
        project:
          type: object
          required:
          - id
          properties:
            id:
              type: string
              example: 123
        token:
          type: object
          properties:
            id:
              type: string
              example: 12345
            description:
              type: string
              example: user@example.com
        status:
          $ref: '#/components/schemas/JobStatus'
        desiredStatus:
          type: string
          nullable: true
          enum:
          - processing
          - terminating
        component:
          type: string
          example: keboola.ex-db-snowflake
        mode:
          type: string
          enum:
          - run
          - debug
        tag:
          type: string
          nullable: true
          example: 1.2.3
        config:
          type: string
          nullable: true
          example: '123456789'
        configRow:
          type: string
          nullable: true
          example: '123456789'
        configData:
          type: object
          nullable: true
          example:
            parameters:
              foo: bar
              baz: mek
        result:
          type: object
          nullable: true
          properties:
            images:
              type: array
              items:
                type: object
                properties:
                  digests:
                    type: array
                    items:
                      type: string
                  id:
                    type: string
            configVersion:
              type: integer
            message:
              type: string
        createdTime:
          type: string
          format: date-time
          example: '2019-06-21T09:12:33.001Z'
        startTime:
          type: string
          format: date-time
          nullable: true
          example: '2019-06-21T09:12:33.001Z'
        endTime:
          type: string
          format: date-time
          nullable: true
          example: '2019-06-21T09:12:33.001Z'
        delayedStartTime:
          type: string
          format: date-time
          nullable: true
          example: '2019-06-21T09:12:33.001Z'
          description: Delayed start time - the earliest time when the job can be started
        durationSeconds:
          type: integer
          nullable: true
          example: 165
        isFinished:
          type: boolean
          example: false
        url:
          type: string
          example: https://queue.east-us-2.azure.keboola-testing.com/jobs/123456789
        variableValuesId:
          type: string
          nullable: true
          example: '1234'
        variableValuesData:
          type: object
          nullable: true
          properties:
            values:
              type: array
              items:
                type: object
                properties:
                  name:
                    type: string
                  value:
                    type: string
          example:
            items:
            - name: testVariable
              value: testValue
        backend:
          type: object
          nullable: true
          properties:
            type:
              type: string
            containerType:
              type: string
            context:
              type: string
          example:
            type: small
            context: 123_extractor
        metrics:
          type: object
          nullable: true
          properties:
            storage:
              type: object
              properties:
                inputTablesBytesSum:
                  type: integer
                outputTablesBytesSum:
                  type: integer
            backend:
              type: object
              properties:
                type:
                  type: string
                containerType:
                  type: string
                context:
                  type: string
              example:
                type: small
                context: 123_extractor
        type:
          $ref: '#/components/schemas/JobType'
        orchestrationTaskId:
          type: string
          nullable: true
          minLength: 1
        previousJobId:
          type: string
          nullable: true
          minLength: 1
        onlyOrchestrationTaskIds:
          type: array
          nullable: true
          minItems: 1
          uniqueItems: true
          items:
            type: string
            nullable: false
            minLength: 1
    JobStatus:
      type: string
      enum:
      - created
      - waiting
      - processing
      - success
      - warning
      - error
      - terminating
      - terminated
      - cancelled
    OpenLineageCompleteEvent:
      type: object
      required:
      - eventType
      - eventTime
      - run
      - job
      - producer
      - outputs
      description: Job execution end event, including information about output mapping tables.
      properties:
        eventType:
          type: string
          example: COMPLETE
        eventTime:
          type: string
          format: date-time
          description: Job execution end time
        run:
          type: object
          required:
          - runId
          properties:
            runId:
              type: string
              format: uuid
        job:
          type: object
          required:
          - namespace
          - name
          properties:
            namespace:
              type: string
              example: connection.north-europe.azure.keboola.com/project/1234
            name:
              type: string
              example: keboola.snowflake-transformation-123456
        producer:
          type: string
          format: uri
          description: Keboola Connection stack uri
          example: https://connection.north-europe.azure.keboola.com
        outputs:
          type: array
          description: Output Mapping table list
          items:
            type: object
            required:
            - namespace
            - name
            - facets
            properties:
              namespace:
                type: string
                example: connection.north-europe.azure.keboola.com/project/1234
              name:
                type: string
                example: out.c-orders.dailyStats"
                description: Table ID in Keboola Storage
              facets:
                type: object
                required:
                - schema
                properties:
                  schema:
                    type: object
                    required:
                    - _producer
                    - _schemaURL
                    - fields
                    properties:
                      _producer:
                        type: string
                        format: uri
                        example: https://connection.north-europe.azure.keboola.com
                      _schemaURL:
                        type: string
                        example: https://openlineage.io/spec/1-0-2/OpenLineage.json#/$defs/OutputDatasetFacet
                      fields:
                        type: array
                        items:
                          type: object
                          required:
                          - name
                          properties:
                            name:
                              type: string
                        example:
                        - name: date
                        - name: ordersCount
                        - name: totalPriceEuroSum
    OpenLineageStartEvent:
      type: object
      required:
      - eventType
      - eventTime
      - run
      - job
      - producer
      - inputs
      description: Job execution start event, including information about input mapping tables.
      properties:
        eventType:
          type: string
          example: START
        eventTime:
          type: string
          format: date-time
          description: Job execution start time
        run:
          type: object
          required:
          - runId
          properties:
            runId:
              type: string
              format: uuid
            facets:
              type: object
              required:
              - parent
              properties:
                parent:
                  type: object
                  required:
                  - _producer
                  - _schemaURL
                  - run
                  - job
                  properties:
                    _producer:
                      type: string
                      format: uri
                      example: https://connection.north-europe.azure.keboola.com
                    _schemaURL:
                      type: string
                      example: https://openlineage.io/spec/facets/1-0-0/ParentRunFacet.json#/$defs/ParentRunFacet
                    run:
                      type: object
                      required:
                      - runId
                      properties:
                        runId:
                          type: string
                          format: uuid
                    job:
                      type: object
                      required:
                      - namespace
                      - name
                      properties:
                        namespace:
                          type: string
                          example: connection.north-europe.azure.keboola.com/project/1234
                        name:
                          type: string
                          example: keboola.orchestrator-123
        job:
          type: object
          required:
          - namespace
          - name
          properties:
            namespace:
              type: string
              example: connection.north-europe.azure.keboola.com/project/1234
            name:
              type: string
              example: keboola.snowflake-transformation-123456
        producer:
          type: string
          format: uri
          description: Keboola Connection stack uri
          example: https://connection.north-europe.azure.keboola.com
        inputs:
          type: array
          description: Input Mapping table list
          items:
            type: object
            required:
            - namespace
            - name
            - facets
            properties:
              namespace:
                type: string
                example: connection.north-europe.azure.keboola.com/project/1234
              name:
                type: string
                example: in.c-kds-team-ex-shoptet-permalink-1234567.orders
                description: Table ID in Keboola Storage
              facets:
                type: object
                required:
                - schema
                properties:
                  schema:
                    type: object
                    required:
                    - _producer
                    - _schemaURL
                    - fields
                    properties:
                      _producer:
                        type: string
                        format: uri
                        example: https://connection.north-europe.azure.keboola.com
                      _schemaURL:
                        type: string
                        example: https://openlineage.io/spec/1-0-2/OpenLineage.json#/$defs/InputDatasetFacet
                      fields:
                        type: array
                        items:
                          type: object
                          required:
                          - name
                          properties:
                            name:
                              type: string
                        example:
                        - name: code
                        - name: date
                        - name: totalPriceWithVat
                        - name: currency
    JobType:
      type: string
      enum:
      - standard
      - container
      - phaseContainer
      - orchestrationContainer
      - retryContainer
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-StorageApi-Token