Jobs API

Base URL: https://jobs.opteryx.app

Overview

Job submission, execution status tracking, result retrieval, recent-query listing, and edit-time statement checking.

Job flow

Jobs run asynchronously: submitting a query returns immediately with an execution_id, and the query keeps running in the background until you poll it to completion.

• Poll status, not results. GET .../status is cheap and returns results_url once the job is done; GET .../results is what actually pages through the data, num_rows/offset at a time, following next_page for more.
• results and download are independent, not exclusive. Pull a page inline with results to inspect it in your app, or stream the whole set with download as CSV, newline-delimited JSON, or Parquet — call either, neither, or both once the job has finished.

Endpoints

Check a SQL statement without running it

Request: post/api/v1/check

Tags: Query Check

Resolve and type-check one statement against the catalog, as the caller, and report what was found: a positioned error to underline, the result shape, and the relations and columns in scope for completion. Reads no data and changes nothing, so it is safe to call as a statement is typed. A statement that is wrong is a 200 with ok: false - the error is the answer, not a failure of the request.

Header Parameters

• authorization string | null [header; optional]

Request Body

• Content-Type: application/json Schema: QueryCheckRequest
  • sql_text string [required] One SQL statement to check. Not a batch.
  • parameters object | null [optional] Values for the statement's :name placeholders. Anything not passed is resolved from the caller's saved variables, exactly as job submission resolves them - see the Variables API.

Responses

• 200 — Successful Response (application/json QueryCheckResponse)
• 422 — Validation Error (application/json HTTPValidationError)

Try it live

Create and execute SQL job

Request: post/api/v1/jobs

Tags: Jobs Management

Submit a SQL job for execution. :name placeholders in sql_text are resolved from the parameters field, falling back to the caller's saved variables for anything not passed explicitly - see parameters below and the Variables API.

Header Parameters

• authorization string | null [header; optional]

Request Body

• Content-Type: application/json Schema: JobCreateRequest
  • sql_text string [required] SQL statement to execute
  • client_info object | null [optional] Client information, e.g. application name/version
  • parameters object | null [optional] Values for any :name placeholders in sql_text, as key-value pairs. Values passed here always take priority. Any placeholder the query references that isn't included here is automatically resolved from the caller's saved variables (see the Variables API) - this is what lets a shared query stay generic (e.g. WHERE department = :department) while each caller's own saved value fills in without them passing it explicitly. A placeholder that's neither passed nor saved is left unresolved, and the job fails at execution with a parameter-not-defined error.

Responses

• 201 — Successful Response (application/json JobCreateResponse)
• 422 — Validation Error (application/json HTTPValidationError)

Try it live

Retrieve recent user queries

Request: get/api/v1/jobs/recent

Tags: Jobs Management

Get recent user queries.

Query Parameters

• filter string | null [query; optional]

Header Parameters

• authorization string | null [header; optional]

Responses

• 200 — Successful Response (application/json array<QueryJob>)
• 422 — Validation Error (application/json HTTPValidationError)

Try it live

Download job results

Request: get/api/v1/jobs/{identifier}/download

Tags: Jobs Management

Download the results of a previously submitted job as CSV, newline-delimited JSON, or Parquet.

Path Parameters

• identifier string [path; required]

Query Parameters

• file_format string [query; optional] Allowed values: csv, json, parquet Default: csv
• limit integer [query; optional] Default: 10000
• offset integer [query; optional] Default: 0

Header Parameters

• authorization string | null [header; optional]

Responses

• 200 — Successful Response (application/json object)
• 422 — Validation Error (application/json HTTPValidationError)

Try it live

Get job results

Request: get/api/v1/jobs/{identifier}/results

Tags: Jobs Management

Retrieve the results of a previously submitted job.

Path Parameters

• identifier string [path; required]

Query Parameters

• num_rows integer [query; optional] Default: 5000
• offset integer [query; optional] Default: 0
• verbose boolean [query; optional] Default: false

Header Parameters

• authorization string | null [header; optional]

Responses

• 200 — Successful Response (application/json JobResultsResponse)
• 422 — Validation Error (application/json HTTPValidationError)

Try it live

Get job status

Request: get/api/v1/jobs/{identifier}/status

Tags: Jobs Management

Retrieve the execution status of a previously submitted job.

Path Parameters

• identifier string [path; required]

Header Parameters

• authorization string | null [header; optional]

Responses

• 200 — Successful Response (application/json JobStatusResponse)
• 422 — Validation Error (application/json HTTPValidationError)

Try it live

List saved variables

Request: get/api/v1/variables

Tags: Variables

List the caller's saved query-parameter variables.

Header Parameters

• authorization string | null [header; optional]

Responses

• 200 — Successful Response (application/json VariableListResponse)
• 422 — Validation Error (application/json HTTPValidationError)

Try it live

Create or update a saved variable

Request: put/api/v1/variables/{name}

Tags: Variables

Create (or replace) a named query-parameter variable for the caller.

Path Parameters

• name string [path; required]

Header Parameters

• authorization string | null [header; optional]

Request Body

• Content-Type: application/json Schema: VariableUpsertRequest
  • type string [required] One of 'string', 'number', or 'boolean'
  • value object [required] The variable's value; its JSON type must match type

Responses

• 200 — Successful Response (application/json VariableListResponse)
• 422 — Validation Error (application/json HTTPValidationError)

Try it live

Delete a saved variable

Request: delete/api/v1/variables/{name}

Tags: Variables

Delete a named query-parameter variable for the caller.

Path Parameters

• name string [path; required]

Header Parameters

• authorization string | null [header; optional]

Responses

• 204 — Successful Response
• 422 — Validation Error (application/json HTTPValidationError)

Try it live