Jobs API
Monitor job progress and cancel running jobs.
List Jobs
Pagination offset (default: 0)
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
}
max_retries times (default: 3).
