> ## 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 API

> Monitor and manage sync jobs

# Jobs API

Monitor job progress and cancel running jobs.

## List Jobs

<ParamField query="source_id" type="string">
  Filter jobs by source ID
</ParamField>

<ParamField query="skip" type="integer">
  Pagination offset (default: 0)
</ParamField>

<ParamField query="limit" type="integer">
  Pagination limit (default: 50, max: 100)
</ParamField>

<RequestExample>
  ```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}"
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
    "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
  }
  ```
</ResponseExample>

## Get Job

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

<ResponseExample>
  ```json theme={null}
  {
    "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
  }
  ```
</ResponseExample>

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

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

<ResponseExample>
  ```json theme={null}
  {
    "id": "job-uuid",
    "status": "cancelled",
    "...": "..."
  }
  ```
</ResponseExample>

<Note>
  Only `pending` and `running` jobs can be cancelled. Cancelling a completed or failed job returns an error.
</Note>

## Failed Jobs

When a job fails:

```json theme={null}
{
  "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).