---
title: "Jobs"
description: "Schedule recurring backend work for StackMachine apps."
---

> Documentation Index
> Fetch the complete documentation index at: https://docs.stackmachine.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Jobs

Cron jobs run recurring backend work on a schedule. Starting with the JavaScript SDK version 0.5.0, you can create and manage command or HTTP cron jobs directly from your application code.

> These APIs require `stackmachine` version 0.5.0 or later. Cron jobs created through the SDK use `client.apps.cronjobs`.

## Features

### Command and HTTP targets

Create an `EXECUTE` job to run a command in the app environment, or a `FETCH` job to call an HTTP path on the app. A job's target kind is fixed when it is created.

### Lifecycle management

Create, retrieve, update, pause, and delete API-sourced cron jobs without leaving the SDK.

### Filtering and pagination

List an app's cron jobs, filter them by `EXECUTE` or `FETCH`, sort by newest or oldest, and use the standard SDK pagination helpers.

### Execution controls

Set whether a job is enabled and optionally configure retries, maximum schedule drift, and a timeout when creating or updating it.

## Common workflow

1. Choose the app and decide whether the job should execute a command or fetch an HTTP path.
2. Create the cron job with a name, cron schedule, and exactly one target.
3. List or retrieve jobs to inspect their current configuration.
4. Update the schedule or enabled state, or delete an API-sourced job when it is no longer needed.

## SDK examples

### Create command and HTTP cron jobs

Schedule a nightly cleanup command and a five-minute HTTP health check. Pass exactly one of `execute` or `fetch` when creating each job.

```javascript
const cleanup = await client.apps.cronjobs.create({
  app: "da_XYZ",
  name: "cleanup",
  schedule: "0 2 * * *",
  execute: {
    command: "python cleanup.py --older-than '30 days'",
    env: { LOG_LEVEL: "info" },
  },
});
console.log(cleanup.id, cleanup.kind); // EXECUTE

const healthcheck = await client.apps.cronjobs.create({
  app: "da_XYZ",
  name: "healthcheck",
  schedule: "*/5 * * * *",
  fetch: {
    path: "/health",
    method: "GET",
    expectStatusCodes: [200],
  },
});
console.log(healthcheck.id, healthcheck.kind); // FETCH
```

```python
cleanup = client.apps.cronjobs.create(
    app="da_XYZ", name="cleanup", schedule="0 2 * * *",
    execute={
        "command": "python cleanup.py --older-than '30 days'",
        "env": {"LOG_LEVEL": "info"},
    },
)
print(cleanup.id, cleanup.kind)  # EXECUTE

healthcheck = client.apps.cronjobs.create(
    app="da_XYZ", name="healthcheck", schedule="*/5 * * * *",
    fetch={"path": "/health", "method": "GET", "expect_status_codes": [200]},
)
print(healthcheck.id, healthcheck.kind)  # FETCH
```

### List and retrieve cron jobs

List jobs for an app with optional kind and sort filters, then retrieve one job by ID.

```javascript
const cronJobs = await client.apps.cronjobs
  .list({
    app: "da_XYZ",
    kind: "EXECUTE",
    sortBy: "NEWEST",
    limit: 25,
  })
  .autoPagingToArray({ limit: 100 });

for (const job of cronJobs) {
  console.log(job.id, job.name, job.schedule, job.enabled);
}

const job = await client.apps.cronjobs.retrieve("cronjob_XYZ");
console.log(job.kind, job.target);
```

```python
from itertools import islice

cron_jobs = list(islice(client.apps.cronjobs.list(
    app="da_XYZ", kind="EXECUTE", sort_by="NEWEST", limit=25,
), 100))
for job in cron_jobs:
    print(job.id, job.name, job.schedule, job.enabled)

job = client.apps.cronjobs.retrieve("cronjob_XYZ")
print(job.kind, job.target)
```

### Update and delete a cron job

Pause a job without deleting it, change its schedule, or permanently delete an API-sourced job.

```javascript
const paused = await client.apps.cronjobs.update("cronjob_XYZ", {
  enabled: false,
  schedule: "0 3 * * *",
});
console.log(paused.name, paused.enabled, paused.schedule);

// Permanently delete an API-sourced cron job when it is no longer needed.
await client.apps.cronjobs.del("cronjob_XYZ");
```

```python
paused = client.apps.cronjobs.update(
    "cronjob_XYZ", enabled=False, schedule="0 3 * * *",
)
print(paused.name, paused.enabled, paused.schedule)

# Permanently delete an API-sourced cron job when it is no longer needed.
client.apps.cronjobs.delete("cronjob_XYZ")
```

## Related docs

- [Deploy from files](/apps/deployments/from-files)
- [App logs](/usage/logs)
- [Mail](/mails)

> Source: [stackmachine/sdks](https://github.com/stackmachine/sdks/tree/main/js) JavaScript examples.

Source: https://docs.stackmachine.com/jobs/index.mdx