> For the complete documentation index, see [llms.txt](https://developer.celigo.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.celigo.com/cli/commands/jobs.md).

# jobs

Flow execution history and control — inspect past runs, monitor what's running now, download produced files, and pull errors for a specific run.

**REST API**: [Jobs](https://developer.celigo.com/api/api-reference/monitoring/jobs)

**OpenAPI spec**: `dist/job.yml` in `@celigo/api-specs` — see [OpenAPI specs](https://developer.celigo.com/api/using-the-api/openapi-specs)

```
celigo jobs <subcommand> [args] [flags]
```

Supports all [global flags](/cli/getting-started/global-flags.md).

***

## Subcommands

| Subcommand             | Purpose                                                                          |
| ---------------------- | -------------------------------------------------------------------------------- |
| `get <id>`             | Fetch one job; parent jobs auto-expand to the full family (parent + child jobs). |
| `list`                 | Last resort: list historical jobs with strict, index-backed filters.             |
| `current`              | List currently-running jobs.                                                     |
| `cancel <id>`          | Cancel a running job.                                                            |
| `diagnostics <id>`     | Fetch diagnostics for a job.                                                     |
| `download-files <id>`  | List signed download URLs, or fetch a file's bytes (`--file-id`, `-o`).          |
| `purge-files <id>`     | Delete stored files for a job.                                                   |
| `errors <id>`          | Open errors attributable to one job (walks the family to resolve scope).         |
| `resolved-errors <id>` | Resolved errors attributable to one job (same resolution as `errors`).           |
| `run-stats`            | Flow run statistics.                                                             |

***

## `celigo jobs get`

Get a job by ID. Top-level run jobs (`type=flow`, `retry`, or `bulk_retry`) auto-expand to the full **family** — the run record with its child jobs inlined under `children` — because a run only carries aggregate counters and the per-step detail lives on the children. Child step jobs (`type=export`/`import`) return just the single record.

**Signature**

```bash
celigo jobs get <id>
```

**Arguments**

| Argument | Type   | Required | Description |
| -------- | ------ | -------- | ----------- |
| `<id>`   | string | Yes      | Job `_id`.  |

**Example**

```bash
celigo jobs get 6a1b2c3d4e5f6a7b8c9d0e1f
```

**Corresponds to**: [`GET /v1/jobs/{_id}`](https://developer.celigo.com/api/api-reference/monitoring/jobs#get-v1-jobs-_id) — and, for parent jobs, [`GET /v1/jobs/{_id}/family`](https://developer.celigo.com/api/api-reference/monitoring/jobs#get-v1-jobs-_id-family).

***

## `celigo jobs list`

Last resort: list historical jobs via the generic jobs endpoint with strict, index-backed filters. Prefer `jobs current` for running/active jobs, `jobs get <id>` for one run (children inlined), and `jobs run-stats` for aggregate history.

> **`jobs list` was restricted in celigo-cli 2026.8.4**, at the platform team's request — free-form `GET /v1/jobs` queries were degrading the shared database for every account. `--type` is now required, only two filter shapes are supported, and the `--export`/`--import` flags were removed (child export/import jobs are not indexed by step ID — scope them by the parent run's job ID with `--flow-job`/`--parent-job`, or use `jobs get <runId>`, which inlines the child jobs). Every rejected combination fails client-side, before any network call, with the supported alternative named.

The two supported filter shapes:

| `--type`             | Required scope                                                     |
| -------------------- | ------------------------------------------------------------------ |
| `flow` or `retry`    | `--integration <id>` or `--flow <id>`                              |
| `export` or `import` | `--flow-job <id>` or `--parent-job <id>` (the parent run's job ID) |

**Signature**

```bash
celigo jobs list --type <flow|retry|export|import> [scope] [flags]
```

**Flags**

| Flag                  | Type                                     | Default | Description                                                                                        |
| --------------------- | ---------------------------------------- | ------- | -------------------------------------------------------------------------------------------------- |
| `--type <type>`       | `flow\|retry\|export\|import`            | —       | **Required.** Job type to list. (The long-defunct `bulk_retry` type is deliberately not accepted.) |
| `--integration <id>`  | string                                   | —       | Scope `--type flow`/`retry` by `_integrationId`.                                                   |
| `--flow <id>`         | string                                   | —       | Scope `--type flow`/`retry` by `_flowId`.                                                          |
| `--flow-job <id>`     | string                                   | —       | Scope `--type export`/`import` by `_flowJobId` (the parent run's job ID).                          |
| `--parent-job <id>`   | string                                   | —       | Scope `--type export`/`import` by `_parentJobId`.                                                  |
| `--status <status>`   | `completed\|failed\|queued\|canceled\|…` | —       | Filter by **one** status (the API has no multi-status filtering).                                  |
| `--created-gte <iso>` | ISO 8601                                 | —       | `createdAt >=` lower bound. Additional narrowing only — not sufficient scope on its own.           |
| `--created-lte <iso>` | ISO 8601                                 | —       | `createdAt <=` upper bound.                                                                        |
| `--started-gte <iso>` | ISO 8601                                 | —       | `startedAt >=` lower bound.                                                                        |
| `--started-lte <iso>` | ISO 8601                                 | —       | `startedAt <=` upper bound.                                                                        |
| `--limit <n>`         | integer                                  | —       | Stop after collecting this many rows (client-side early-stop).                                     |

**Example**

```bash
# Failed runs for one flow in the last 24 hours
celigo jobs list --type flow --flow 5f83a9b2c7d3e8f1a2b3c4d5 \
  --status failed --created-gte "$(date -u -v-24H +%FT%TZ)"

# The child import jobs of one run
celigo jobs list --type import --flow-job 6a1b2c3d4e5f6a7b8c9d0e1f
```

**Corresponds to**: [`GET /v1/jobs?...`](https://developer.celigo.com/api/api-reference/monitoring/jobs#get-v1-jobs) (filters are mapped to `type`, `_integrationId`, `_flowId`, `_flowJobId`, `_parentJobId`, `status`, `createdAt_gte/lte`, `startedAt_gte/lte`).

***

## `celigo jobs current`

List currently-running jobs. Uses the `POST /v1/jobs/current` body-paginated endpoint.

**Signature**

```bash
celigo jobs current [flags]
```

**Flags**

| Flag                 | Type            | Default | Description                                                  |
| -------------------- | --------------- | ------- | ------------------------------------------------------------ |
| `--integration <id>` | string          | —       | Filter by integration ID (sent as `_integrationIds`).        |
| `--flow <id>`        | string          | —       | Filter by flow ID (sent as `_flowIds`).                      |
| `--status <status>`  | comma-separated | —       | One or more of `queued`, `running`, `retrying`, `canceling`. |

> **`--sandbox` was removed in celigo-cli 2026.8.1.** The environment comes from the profile's token, so a flag could contradict it. To query another environment, use a profile whose token targets it. See [Profiles & regions](/cli/getting-started/profiles.md).

**Example**

```bash
# Anything running right now in the profile's environment
celigo jobs current

# Currently-retrying jobs for one integration
celigo jobs current --integration 5f83a9b2c7d3e8f1a2b3c4d5 --status retrying

# The same query against a QA environment
celigo --profile qa jobs current
```

**Corresponds to**: [`POST /v1/jobs/current`](https://developer.celigo.com/api/api-reference/monitoring/jobs#post-v1-jobs-current)

***

## `celigo jobs cancel`

Cancel a running job. Prompts for confirmation unless `-y` is passed.

> ⚠️ **Canceling a running job cannot be undone.** The job stops where it is; records already processed are kept, and the run does not resume.

**Signature**

```bash
celigo jobs cancel <id> [-y]
```

**Arguments**

| Argument | Type   | Required | Description |
| -------- | ------ | -------- | ----------- |
| `<id>`   | string | Yes      | Job `_id`.  |

**Flags**

| Flag        | Type    | Default | Description                   |
| ----------- | ------- | ------- | ----------------------------- |
| `-y, --yes` | boolean | `false` | Skip the confirmation prompt. |

**Example**

```bash
celigo jobs cancel 6a1b2c3d4e5f6a7b8c9d0e1f -y
```

**Corresponds to**: [`PUT /v1/jobs/{_id}/cancel`](https://developer.celigo.com/api/api-reference/monitoring/jobs#put-v1-jobs-_id-cancel)

***

## `celigo jobs diagnostics`

Fetch diagnostics for a job (performance breakdown, retry metadata, etc.).

**Signature**

```bash
celigo jobs diagnostics <id>
```

**Arguments**

| Argument | Type   | Required | Description |
| -------- | ------ | -------- | ----------- |
| `<id>`   | string | Yes      | Job `_id`.  |

**Example**

```bash
celigo jobs diagnostics 6a1b2c3d4e5f6a7b8c9d0e1f --format json
```

**Corresponds to**: [`GET /v1/jobs/{_id}/diagnostics`](https://developer.celigo.com/api/api-reference/monitoring/jobs#get-v1-jobs-_id-diagnostics)

***

## `celigo jobs download-files`

List the signed download URLs for a job's files, or fetch a file's bytes to disk.

* **No flags** — prints the signed download URLs for every file the job produced (it does not fetch the bytes).
* **`--file-id`** — narrows to one file (e.g., an EDI transaction's `s3Key`).
* **`-o`** — fetches the file's bytes and writes them to the given path.

**Where do file ids come from?** `jobs get <id>` returns a `files[]` array; each entry has an `id` (the storage file id), `host` (`s3` or `netsuite`), and `name`. Pass that `id` to `--file-id`. For EDI specifically, the `s3Key` on an `edi-transactions` record is the file id.

**Signature**

```bash
celigo jobs download-files <id> [--file-id <fileId>] [-o <path>]
```

**Arguments**

| Argument | Type   | Required | Description |
| -------- | ------ | -------- | ----------- |
| `<id>`   | string | Yes      | Job `_id`.  |

**Flags**

| Flag                  | Type   | Default | Description                                                           |
| --------------------- | ------ | ------- | --------------------------------------------------------------------- |
| `--file-id <fileId>`  | string | —       | Specific file id (from `jobs get` → `files[].id`, or an EDI `s3Key`). |
| `-o, --output <path>` | path   | —       | Fetch the file's bytes and write them to this path instead of stdout. |

**Example**

```bash
# List signed URLs for every file the job produced
celigo jobs download-files 6a1b2c3d4e5f6a7b8c9d0e1f

# Stream one file to stdout
celigo jobs download-files 6a1b2c3d4e5f6a7b8c9d0e1f --file-id 694b97c4f4f1f4a1b9d9e001

# Save to disk
celigo jobs download-files 6a1b2c3d4e5f6a7b8c9d0e1f --file-id 694b97c4f4f1f4a1b9d9e001 -o ./out.x12
```

**Corresponds to**: [`POST /v1/jobs/{_id}/files/signedURL`](https://developer.celigo.com/api/api-reference/monitoring/jobs#post-v1-jobs-_id-files-signedurl) — called with an empty body to list URLs, or `{ "fileIds": [...] }` when `--file-id` is set. With `-o`, the CLI then `GET`s the returned signed URL to fetch the bytes.

***

## `celigo jobs purge-files`

Delete stored files for a job. The job record itself is not removed. Prompts for confirmation unless `-y` is passed.

> ⚠️ **Purging files is irreversible.** The stored file artifacts are deleted permanently; the job record, diagnostics, and errors remain queryable.

**Signature**

```bash
celigo jobs purge-files <id> [-y]
```

**Arguments**

| Argument | Type   | Required | Description |
| -------- | ------ | -------- | ----------- |
| `<id>`   | string | Yes      | Job `_id`.  |

**Flags**

| Flag        | Type    | Default | Description                   |
| ----------- | ------- | ------- | ----------------------------- |
| `-y, --yes` | boolean | `false` | Skip the confirmation prompt. |

**Example**

```bash
celigo jobs purge-files 6a1b2c3d4e5f6a7b8c9d0e1f -y
```

**Corresponds to**: [`DELETE /v1/jobs/{_id}/files`](https://developer.celigo.com/api/api-reference/monitoring/jobs#delete-v1-jobs-_id-files)

***

## `celigo jobs errors`

Return **open** errors attributable to one job. The CLI resolves the job's flow and export/import steps from its family, then queries the flow-scoped error endpoint filtered by `_flowJobId` plus the job's run window. For resolved errors, use [`jobs resolved-errors`](#celigo-jobs-resolved-errors).

**Signature**

```bash
celigo jobs errors <id>
```

**Arguments**

| Argument | Type   | Required | Description                                                                                                       |
| -------- | ------ | -------- | ----------------------------------------------------------------------------------------------------------------- |
| `<id>`   | string | Yes      | Job `_id`. Parent flow jobs fan out across their children; child jobs walk up to the parent to resolve `_flowId`. |

**Example**

```bash
# Open errors for one run
celigo jobs errors 6a1b2c3d4e5f6a7b8c9d0e1f --format json | jq length
```

**Corresponds to**: [`GET /v1/flows/{_flowId}/{exportOrImportId}/errors`](https://developer.celigo.com/api/api-reference/integrations-and-flows/flows) filtered by `_flowJobId` and an `occurredAt` window — see the flow errors section of the REST API. Returns up to 1000 rows.

***

## `celigo jobs resolved-errors`

Return **resolved** errors attributable to one job. Identical flow + step resolution as [`jobs errors`](#celigo-jobs-errors), but queries the resolved-error endpoint with a `resolvedAt` window.

**Signature**

```bash
celigo jobs resolved-errors <id>
```

**Arguments**

| Argument | Type   | Required | Description                                                                         |
| -------- | ------ | -------- | ----------------------------------------------------------------------------------- |
| `<id>`   | string | Yes      | Job `_id`. Resolved the same way as `jobs errors` (parent fan-out / child walk-up). |

**Example**

```bash
# Errors already resolved for that run
celigo jobs resolved-errors 6a1b2c3d4e5f6a7b8c9d0e1f
```

**Corresponds to**: [`GET /v1/flows/{_flowId}/{exportOrImportId}/resolved`](https://developer.celigo.com/api/api-reference/integrations-and-flows/flows) filtered by `_flowJobId` and a `resolvedAt` window. Returns up to 1000 rows.

***

## `celigo jobs run-stats`

Flow run statistics, grouped by flow/integration.

**Signature**

```bash
celigo jobs run-stats [flags]
```

**Flags**

| Flag                 | Type            | Default | Description                                           |
| -------------------- | --------------- | ------- | ----------------------------------------------------- |
| `--integration <id>` | string          | —       | Filter by integration ID (sent as `_integrationIds`). |
| `--flow <id>`        | string          | —       | Filter by flow ID (sent as `_flowIds`).               |
| `--status <status>`  | comma-separated | —       | One or more of `completed`, `failed`.                 |

> **`--sandbox` was removed in celigo-cli 2026.8.1.** Use a profile whose token targets the environment you want instead.

**Example**

```bash
celigo jobs run-stats --flow 5f83a9b2c7d3e8f1a2b3c4d5 --status completed,failed
```

**Corresponds to**: [`POST /v1/flows/runs/stats`](https://developer.celigo.com/api/api-reference/monitoring/jobs#post-v1-flows-runs-stats)

***

## Gotchas

* **`jobs list` is the last resort, and it enforces its own scope.** `--type` is required, `--type flow`/`retry` must be scoped by integration or flow, and `--type export`/`import` by the parent run's job ID. A `createdAt` bound alone is not sufficient scope, and `--status` takes a single value. Prefer `current`, `get`, and `run-stats` — they answer most questions without the generic endpoint.
* **Child jobs have no `_flowId`.** Export/import-type jobs carry `_parentJobId` (or `_flowJobId`) instead — which is also why `jobs list` scopes them by `--flow-job`/`--parent-job` rather than the removed `--export`/`--import` flags. `jobs errors` walks up to the parent automatically; if you query the flow errors API yourself, do the same walk first.
* **`jobs errors` requires a time window.** The flow error endpoint rejects queries that lack `occurredAt_gte/lte` (or `resolvedAt_gte/lte` for `jobs resolved-errors`). The CLI derives this from `startedAt`/`endedAt` on the job — jobs that haven't ended yet fall back to "now" on the upper bound.
* **`jobs current` and `jobs run-stats` are POST body endpoints**, not GET with a query string. A `read`-mode profile blocks them, because the client gates on the HTTP verb. Use an `operate`-mode profile for these two.
* **Environment comes from the profile, not a flag.** `--sandbox` was removed in celigo-cli 2026.8.1. Every job command reads the environment that the profile's token targets. Add a second profile to query another environment.
* **`jobs download-files` without `-o` does not fetch bytes.** It prints the signed URLs and returns — writing content to disk requires `-o` (optionally with `--file-id` to pick one file).
* **`purge-files` is not the same as cancelling or deleting a job.** It removes the stored file artifacts only; the job record, diagnostics, and errors remain queryable.

## Related

* [audit](/cli/commands/audit.md) — who changed a resource (complement to `jobs` for runtime events).
* [flows](/cli/commands/flows.md) — `flows errors` / `flows resolve-errors` operate on the step-level scope that `jobs errors` resolves into.
* [integrations](/cli/commands/integrations.md) — use `jobs list --type flow --integration <id>` to sweep runs across every flow in one integration.