---
title: "List jobs"
method: GET
path: "/v2/jobs"
tags: ["Jobs"]
---

# List jobs

`GET /v2/jobs`

Lists jobs for the account. Jobs are background processes, such as replacing the filterable metadata attributes.

## Query parameters

- `corpus_key` CorpusKey[]
- `after` string, date-time
- `state` JobState[]
- `limit` integer
- `page_key` string

## Headers

- `Request-Timeout` integer
- `Request-Timeout-Millis` integer

## Response `200`

List of jobs.

- ListJobsResponse — Response containing a list of background jobs and their current states.
  - `jobs` Job[] — An array of jobs.
    - `id` string, required — The ID of the job.
    - `type` 'rebuild_vector_index' | 'replace_filter_attributes' | 'bulk_delete_documents' | 'bulk_update_document_metadata' | 'unknown' — The type of job.
    - `corpus_keys` CorpusKey[] — The corpora that this job belongs to. Some jobs do not belong to any corpus.
    - `state` 'unknown' | 'queued' | 'started' | 'completed' | 'failed' | 'failed_will_retry' | 'aborted' — The state of a background job.
    - `created_at` string, date-time — When the job was created.
    - `started_at` string, date-time — When the job was started.
    - `completed_at` string, date-time — When the job was completed.
    - `created_by_username` string — The username of the user who created the job. This property can be absent, for example when the platform created the job.
    - `comment` string — A human-readable explanation of the job's current status. The format and content depend on the job type. On failure, this property contains the error message. This property can be absent.
    - `progress` JobProgress — Live progress of a running job. Present only while the job is running, and only when retrieving a single job by ID; `listJobs` never populates it. Absence does not indicate failure — read `state` for job health. The counters describe the corpus rebuild the job runs, so a job that drives no rebuild reports nothing here. `pages_pending_import`, `imports_in_flight` and `import_batches_submitted` describe incremental import, which is not enabled for every rebuild. When it is not in use all three report 0 for the whole rebuild, which means "not applicable" rather than "nothing left to do".
      - `phase` 'preparing' | 'scanning' | 'importing' | 'cutting_over' | 'replaying_journals' | 'completed' — The stage of the rebuild that is currently running. A rebuild scans the corpus and imports it into the new indices, then cuts the corpus over to them and replays everything written while it ran. New phases may be added; treat unrecognized values as opaque.
      - `documents_indexed` integer — The number of documents the rebuild has processed out of the corpus so far, counting towards `documents_expected`.
      - `documents_expected` integer — The number of documents the corpus held when the rebuild started, and the total that `documents_indexed` runs towards. Absent when the corpus size could not be determined.
      - `scan_shards` integer — The number of shards the corpus is being scanned in, all read concurrently.
      - `scan_shards_finished` integer — How many of the corpus's scan shards have been read to the end.
      - `pages_pending_import` integer — Staged scan batches waiting to be imported. Bounded by the rebuild's own backpressure, so this does not grow with the size of the corpus. Reports 0 when incremental import is not in use.
      - `import_batches_submitted` integer — Import batches handed to the vector store over the rebuild's lifetime. It only ever climbs. Reports 0 when incremental import is not in use.
      - `imports_in_flight` integer — Import batches submitted to the vector store and still being waited on. Reports 0 when incremental import is not in use.
      - `import_recovery_attempts` integer — How many times the rebuild has had to discard and replay a failed import. A nonzero value means imports are being retried, not that the rebuild has failed. Unlike `import_batches_submitted`, this counts only the rebuild's current stretch of work and restarts at 0 if the rebuild continues past an internal checkpoint.
      - `started_at` string, date-time — When the rebuild these counters describe began, and the instant they are all measured from. It is reported by the rebuild itself, so it is present whenever this object is and does not move for the rebuild's lifetime, whereas `Job.started_at` is recorded on the job and may be absent or differ.
  - `metadata` ListMetadata — The standard metadata in the response of a list operation.
    - `page_key` string — The page key for the next page of results. Pass it as a query parameter to request the next page.

## Other responses

- `403` — Permissions do not allow listing jobs.

---

[API](https://skmtc.net/vectara/apis/vectara-rest-api-v2.md) · [All operations](https://skmtc.net/vectara/apis/vectara-rest-api-v2/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/vectara/vectara-rest-api-v2/versions/e85040b266cc/schema)