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

# Manage data jobs

> List, filter, update metadata, and cancel data jobs.

Use the data jobs API to list and filter jobs, update names and descriptions, and cancel in-progress alignment runs.

## List data jobs

**Endpoint:** `GET /v1/flow/data-jobs` [List data jobs](/flow/reference/get_data_jobs_v1_flow_data_jobs_get)

Returns a paginated list of all data jobs for the authenticated user.

<CodeGroup>
  ```python Python theme={null}
  from seekrai import SeekrFlow

  client = SeekrFlow()

  jobs = client.data_jobs.list()
  for job in jobs.data:
      print(job.id, job.name, job.status, job.created_at)
  ```
</CodeGroup>

### Filter and sort

| Parameter    | Type   | Options                                                                   | Default      |
| ------------ | ------ | ------------------------------------------------------------------------- | ------------ |
| `job_type`   | string | `principle_files`, `context_grounded_files`, `context_grounded_vector_db` | —            |
| `sort_by`    | string | `name`, `created_at`, `job_type`                                          | `created_at` |
| `sort_order` | string | `asc`, `desc`                                                             | `desc`       |
| `limit`      | int    | 1–100                                                                     | 25           |
| `offset`     | int    | ≥ 0                                                                       | 0            |

<CodeGroup>
  ```python Python theme={null}
  # List only principle_files jobs, most recent first
  jobs = client.data_jobs.list(
      job_type="principle_files",
      sort_by="created_at",
      sort_order="desc",
      limit=10,
  )
  for job in jobs.data:
      print(job.id, job.name, job.status)
  ```
</CodeGroup>

## Get job detail

**Endpoint:** `GET /v1/flow/data-jobs/{id}` [Get data job](/flow/reference/get_data_job_v1_flow_data_jobs__data_job_id__get)

Returns the full job detail including ingestion jobs, file records, timeline events, and alignment status. See [Monitor ingestion](/flow/sdk/data-engine/monitor-ingestion) for a field-by-field reference.

<CodeGroup>
  ```python Python theme={null}
  detail = client.data_jobs.retrieve("dj-1234567890")
  print("Status:", detail.status)
  print("Files:", len(detail.files))
  print("Ingestion jobs:", len(detail.ingestion_jobs))
  ```
</CodeGroup>

## Update job attributes

**Endpoint:** `PATCH /v1/flow/data-jobs/{id}` [Update data job](/flow/reference/patch_data_job_v1_flow_data_jobs__data_job_id__patch)

Update the job name, description, system prompt, or vector database ID without recreating the job.

<CodeGroup>
  ```python Python theme={null}
  data_job = client.data_jobs.update(
      "dj-1234567890",
      name="Customer support refresh v2",
      description="Updated scope with airline escalation policies",
      system_prompt="You are an airline support expert. Always cite the policy section.",
  )
  print("Updated name:", data_job.name)
  ```
</CodeGroup>

**Editable fields:**

| Field                | Notes                                                                                         |
| -------------------- | --------------------------------------------------------------------------------------------- |
| `name`               | Keep under 255 characters.                                                                    |
| `description`        | Optional free-text context, scope, or notes.                                                  |
| `system_prompt`      | Required for `principle_files` jobs before starting. Immediately overwrites the stored value. |
| `vector_database_id` | Required for `context_grounded_vector_db` jobs before starting.                               |

<Warning>
  Once alignment starts, job inputs are locked. Attempting to update a running job returns `409 Conflict`.
</Warning>

## Cancel a job

**Endpoint:** `POST /v1/flow/data-jobs/{id}/cancel` [Cancel data job](/flow/reference/cancel_data_job_v1_flow_data_jobs__data_job_id__cancel_post)

Cancels the alignment run associated with the data job. Only applies when alignment is in `pending`, `queued`, or `running` state.

<CodeGroup>
  ```python Python theme={null}
  client.data_jobs.cancel("dj-1234567890")
  print("Job cancelled.")
  ```
</CodeGroup>

Attempting to cancel a job whose alignment is not in a cancellable state returns `304 Not Modified`.