> 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/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/jobs#get-v1-jobs-_id) — and, for parent jobs, [`GET /v1/jobs/{_id}/family`](https://developer.celigo.com/api/api-reference/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/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/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/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/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/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/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/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/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/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.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://developer.celigo.com/cli/commands/jobs.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.