Jobs

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

Job Lifecycle

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

curl https://api.trygroundai.com/jobs/{job_id} \
  -H "Authorization: Bearer gnd_your_api_key"

Response:

{
  "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

# 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

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

Getting Started

Core Concepts

Guides

Jobs

Jobs

Job Lifecycle

Job Stages

Job Metrics

API Operations

Get Job Status

List Jobs

Cancel Job

Error Handling

Idempotency

​Jobs

​Job Lifecycle

​Job Stages

​Job Metrics

​API Operations

​Get Job Status

​List Jobs

​Cancel Job

​Error Handling

​Idempotency

Jobs

Job Lifecycle

Job Stages

Job Metrics

API Operations

Get Job Status

List Jobs

Cancel Job

Error Handling

Idempotency