Skip to main content

​
Jobs

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

​
Job Lifecycle

​
Job Stages

Each job progresses through stages:
StageDescriptionProgress
queuedWaiting in Redis queue0%
fetchDownloading content10%
parseExtracting text25%
chunkSplitting into chunks40%
embedGenerating embeddings60%
indexStoring in database80%
finalizeUpdating metadata95%

​
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