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

# Jobs

> Understanding sync jobs in Ground

# Jobs

Jobs are asynchronous operations that sync content from sources into Ground's index.

## Job Lifecycle

```mermaid theme={null}
flowchart LR
  pending[Pending] --> running[Running]
  running --> completed[Completed]
  running --> failed[Failed]
  pending --> cancelled[Cancelled]
```

## Job Stages

Each job progresses through stages:

| Stage      | Description            | Progress |
| ---------- | ---------------------- | -------- |
| `queued`   | Waiting in Redis queue | 0%       |
| `fetch`    | Downloading content    | 10%      |
| `parse`    | Extracting text        | 25%      |
| `chunk`    | Splitting into chunks  | 40%      |
| `embed`    | Generating embeddings  | 60%      |
| `index`    | Storing in database    | 80%      |
| `finalize` | Updating metadata      | 95%      |

## Job Metrics

Jobs track:

* `files_processed`: Number of files/pages processed
* `chunks_created`: New chunks added
* `chunks_updated`: Existing chunks modified
* `chunks_deleted`: Old chunks removed

## API Operations

### Get Job Status

```bash theme={null}
curl https://api.trygroundai.com/jobs/{job_id} \
  -H "Authorization: Bearer gnd_your_api_key"
```

Response:

```json theme={null}
{
  "id": "job-uuid",
  "source_id": "source-uuid",
  "status": "running",
  "stage": "embed",
  "progress_percent": 60,
  "progress_message": "Generating embeddings...",
  "files_processed": 150,
  "chunks_created": 0,
  "chunks_updated": 0,
  "chunks_deleted": 0,
  "created_at": "2026-01-17T10:00:00Z",
  "started_at": "2026-01-17T10:00:05Z"
}
```

### List Jobs

```bash theme={null}
# All jobs
curl https://api.trygroundai.com/jobs \
  -H "Authorization: Bearer gnd_your_api_key"

# Jobs for a specific source
curl https://api.trygroundai.com/jobs?source_id={source_id} \
  -H "Authorization: Bearer gnd_your_api_key"
```

### Cancel Job

```bash theme={null}
curl -X POST https://api.trygroundai.com/jobs/{job_id}/cancel \
  -H "Authorization: Bearer gnd_your_api_key"
```

## Error Handling

Failed jobs include:

* `error_message`: Human-readable error description
* `error_details`: Structured error information

Jobs have automatic retry logic:

* `retry_count`: Current retry attempt
* `max_retries`: Maximum retries (default: 3)

## Idempotency

Jobs are designed to be idempotent and resumable:

* Content hashes prevent duplicate processing
* Incremental updates only modify changed chunks
* Worker can restart at any stage checkpoint