Keboola jobs API
The jobs API from Keboola — 13 operation(s) for jobs.
OpenAPI Specification
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':
descri
# --- truncated at 32 KB (67 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/keboola/refs/heads/main/openapi/keboola-jobs-api-openapi.yml