Jobs API

These endpoints manage scheduled and on-demand jobs for your projects. A job defines the command to run, the CronJob schedule, and notification settings. Each project can have multiple jobs.

GET /api/v1/projects/:id/jobs

Returns all jobs configured for a project.

Path Parameters

Parameter	Type	Description
`id`	string	Project ID

Response

{
  "jobs": [
    {
      "id": "job_abc123",
      "project_id": "proj_xyz",
      "name": "scheduled-run",
      "description": "Nightly refresh of all models",
      "command": "sqlmesh run --select-model '*'",
      "schedule": "0 2 * * *",
      "enabled": true,
      "resources": {},
      "environment": {},
      "slack_channel": "#data-alerts",
      "slack_alerts_enabled": true,
      "slack_alert_on_success": false,
      "webhook_enabled": false,
      "created_at": "2026-01-20T09:00:00Z",
      "updated_at": "2026-02-15T11:30:00Z"
    }
  ],
  "total": 1
}

POST /api/v1/projects/:id/jobs

Creates a new job for a project. If the project is deployed, the Kubernetes CronJob is created automatically.

For dbt projects, command must be a valid dbt CLI invocation (e.g. dbt build, dbt run --select models/core). Shell metacharacters (;, &&, |, etc.) are rejected.

Path Parameters

Parameter	Type	Description
`id`	string	Project ID

Request Body

{
  "name": "nightly-refresh",
  "description": "Full model refresh at 2 AM",
  "command": "sqlmesh run --select-model '*'",
  "schedule": "0 2 * * *",
  "enabled": true,
  "slack_channel": "#data-alerts",
  "slack_alerts_enabled": true,
  "slack_alert_on_success": false
}

Field	Type	Required	Description
`name`	string	yes	Job name (unique per project)
`command`	string	yes	Command to execute. For SQLMesh: any `sqlmesh` invocation. For dbt: must start with `dbt` and use an allowed subcommand.
`schedule`	string	yes	Cron expression (e.g. `"0 2 * * *"`)
`description`	string	no	Human-readable description
`enabled`	boolean	no	Whether the CronJob is active (default: `true`)
`resources`	object	no	Kubernetes resource overrides for this job
`environment`	object	no	Environment variable overrides for this job
`slack_channel`	string	no	Slack channel to send alerts to (e.g. `"#data-alerts"`)
`slack_alerts_enabled`	boolean	no	Enable Slack failure alerts (default: `false`)
`slack_alert_on_success`	boolean	no	Also alert on success (default: `false`)
`webhook_url`	string	no	URL to POST job status events to (dbt projects only)
`webhook_headers`	object	no	Additional HTTP headers for webhook requests (dbt projects only)
`webhook_events`	array	no	Events to deliver: e.g. `["success", "failure"]` (dbt projects only)
`webhook_enabled`	boolean	no	Enable webhook delivery (dbt projects only)

Response

Returns 201 Created with the created job object.

PUT /api/v1/projects/:id/jobs/:job_id

Updates an existing job. Only supplied fields are changed. If the project is deployed, the Kubernetes CronJob is updated.

Path Parameters

Parameter	Type	Description
`id`	string	Project ID
`job_id`	string	Job ID

Request Body

Same fields as create, all optional.

Response

Returns 200 OK with the updated job object.

DELETE /api/v1/projects/:id/jobs/:job_id

Deletes a job and removes the corresponding Kubernetes CronJob if the project is deployed.

Path Parameters

Parameter	Type	Description
`id`	string	Project ID
`job_id`	string	Job ID

Response

{
  "message": "Job deleted successfully"
}

POST /api/v1/projects/:id/jobs/:job_id/trigger

Triggers an immediate, one-off run of a specific job. The run is tracked as a job run with triggered_by: "manual".

For dbt projects, you can optionally override the job's configured command for this single run.

Path Parameters

Parameter	Type	Description
`id`	string	Project ID
`job_id`	string	Job ID

Request Body (optional)

{
  "command_override": "dbt run --select models/core"
}

Field	Type	Required	Description
`command_override`	string	no	Override the job's command for this run only (dbt projects only, must be a valid dbt command)

Response

{
  "job_run_id": "run_abc123",
  "job_name": "analytics-nightly-refresh-20260428-120000",
  "status": "pending",
  "message": "Run triggered successfully"
}

GET /api/v1/jobs

Returns running and recently completed Kubernetes job objects across all projects in your organization. This reflects live Kubernetes state, not the job run database records.

Query Parameters

Parameter	Type	Description
`status`	string	Filter by job status
`project`	string	Filter by project name
`limit`	integer	Maximum results to return

Response

{
  "jobs": [
    {
      "id": "analytics-nightly-refresh-20260428-020000",
      "project": "analytics",
      "status": "running",
      "start_time": "2026-04-28T02:00:00Z"
    }
  ],
  "total": 1
}

GET /api/v1/jobs/:id

Returns a single Kubernetes job object by name.

Path Parameters

Parameter	Type	Description
`id`	string	Kubernetes job name

GET /api/v1/jobs/:id/logs

Returns logs from the pod that executed a Kubernetes job.

Path Parameters

Parameter	Type	Description
`id`	string	Kubernetes job name

Query Parameters

Parameter	Type	Default	Description
`tail`	integer	100	Number of log lines to return

Response

{
  "jobId": "analytics-nightly-refresh-20260428-020000",
  "logs": "..."
}

GET /api/v1/runs/:runId

Returns a single job run record from the database.

Path Parameters

Parameter	Type	Description
`runId`	string	Job run ID

Response

A JobRun object:

{
  "id": "run_abc123",
  "project_id": "proj_xyz",
  "job_id": "job_abc123",
  "job_name": "analytics-nightly-refresh-20260428-020000",
  "cronjob_name": "nightly-refresh",
  "namespace": "org-acme",
  "job_type": "run",
  "status": "success",
  "start_time": "2026-04-28T02:00:00Z",
  "end_time": "2026-04-28T02:12:34Z",
  "duration_seconds": 754.1,
  "triggered_by": "scheduled",
  "created_at": "2026-04-28T02:00:00Z",
  "updated_at": "2026-04-28T02:12:34Z"
}

GET /api/v1/runs/:runId/logs

Returns stored logs for a completed job run.

Path Parameters

Parameter	Type	Description
`runId`	string	Job run ID