Jobs API

Monitor job progress and cancel running jobs.

List Jobs

string

Filter jobs by source ID

integer

Pagination offset (default: 0)

integer

Pagination limit (default: 50, max: 100)

# 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}"

{
  "jobs": [
    {
      "id": "job-uuid",
      "source_id": "source-uuid",
      "status": "completed",
      "stage": "finalize",
      "progress_percent": 100,
      "progress_message": "Done",
      "files_processed": 45,
      "chunks_created": 42,
      "chunks_updated": 3,
      "chunks_deleted": 0,
      "created_at": "2026-01-17T10:00:00Z",
      "started_at": "2026-01-17T10:00:05Z",
      "completed_at": "2026-01-17T10:05:00Z"
    }
  ],
  "total": 1
}

Get Job

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

{
  "id": "job-uuid",
  "source_id": "source-uuid",
  "status": "running",
  "stage": "embed",
  "progress_percent": 60,
  "progress_message": "Generating embeddings...",
  "stage_details": {
    "chunks_embedded": 150,
    "total_chunks": 250
  },
  "files_processed": 250,
  "chunks_created": 0,
  "chunks_updated": 0,
  "chunks_deleted": 0,
  "error_message": null,
  "error_details": null,
  "retry_count": 0,
  "created_at": "2026-01-17T10:00:00Z",
  "started_at": "2026-01-17T10:00:05Z",
  "completed_at": null
}

Job Status Values

Status	Description
`pending`	Job created, waiting to be processed
`running`	Job currently executing
`completed`	Job finished successfully
`failed`	Job failed with error
`cancelled`	Job was cancelled

Job Stages

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

Cancel Job

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

{
  "id": "job-uuid",
  "status": "cancelled",
  "...": "..."
}

Only pending and running jobs can be cancelled. Cancelling a completed or failed job returns an error.

Failed Jobs

When a job fails:

{
  "id": "job-uuid",
  "status": "failed",
  "stage": "fetch",
  "error_message": "Failed to fetch URL: 404 Not Found",
  "error_details": {
    "url": "https://example.com/openapi.json",
    "status_code": 404
  },
  "retry_count": 3
}

Jobs automatically retry up to max_retries times (default: 3).

​Jobs API

​List Jobs

​Get Job

​Job Status Values

​Job Stages

​Cancel Job

​Failed Jobs

Jobs API

List Jobs

Get Job

Job Status Values

Job Stages

Cancel Job

Failed Jobs