# Jobs API

Endpoints for managing background jobs.

## Get Job Status

**Endpoint**: `GET /api/job_status.php`

Get the current status of a background job.

### Parameters

- `job_id` (required): Job ID

### Response

```json
{
  "status": "success",
  "job_status": "completed",
  "job": {
    "id": 456,
    "job_type": "hotspot_analysis",
    "status": "completed",
    "progress": 100,
    "params": { ... },
    "result": {
      "dataset_id": 789,
      "dataset_name": "Hot Spot Results",
      "table_name": "spatial_data_789"
    },
    "created_at": "2024-01-01T00:00:00Z",
    "started_at": "2024-01-01T00:01:00Z",
    "finished_at": "2024-01-01T00:05:00Z"
  }
}
```

### Job Statuses

- `queued`: Job is waiting to be processed
- `running`: Job is currently being processed
- `completed`: Job completed successfully
- `failed`: Job failed with an error

### Example

```bash
curl -X GET "https://example.com/api/job_status.php?job_id=456" \
  -H "Cookie: PHPSESSID=..."
```

## Cancel Job

**Endpoint**: `POST /api/job_cancel.php`

Cancel a queued or running job.

### Request Body

```json
{
  "job_id": 456
}
```

### Response

```json
{
  "status": "success",
  "message": "Job cancelled successfully"
}
```

### Notes

- Only queued or running jobs can be cancelled
- Completed or failed jobs cannot be cancelled
- Users can only cancel their own jobs (admins can cancel any job)

## List User Jobs

**Endpoint**: `GET /api/jobs/status.php`

List all jobs for the current user.

### Parameters

- `status` (optional): Filter by status (queued, running, completed, failed)
- `job_type` (optional): Filter by job type
- `limit` (optional): Maximum results (default: 50)
- `offset` (optional): Result offset (default: 0)

### Response

```json
{
  "status": "success",
  "jobs": [
    {
      "id": 456,
      "job_type": "hotspot_analysis",
      "status": "completed",
      "progress": 100,
      "created_at": "2024-01-01T00:00:00Z",
      "finished_at": "2024-01-01T00:05:00Z"
    }
  ],
  "total": 10,
  "limit": 50,
  "offset": 0
}
```

### Example

```bash
curl -X GET "https://example.com/api/jobs/status.php?status=running&limit=10" \
  -H "Cookie: PHPSESSID=..."
```

## Job Result Structure

Completed jobs include a `result` field with job-specific information:

### Hot Spot Analysis Result

```json
{
  "dataset_id": 789,
  "dataset_name": "Hot Spot Results",
  "table_name": "spatial_data_789",
  "row_count": 1000,
  "storage_type": "table"
}
```

### Outlier Analysis Result

```json
{
  "dataset_id": 790,
  "dataset_name": "Outlier Results",
  "table_name": "spatial_data_790",
  "row_count": 50,
  "outlier_count": 50
}
```

### Nearest Analysis Result

```json
{
  "dataset_id": 791,
  "dataset_name": "Nearest Results",
  "table_name": "spatial_data_791",
  "row_count": 500,
  "source_dataset_id": 123,
  "target_dataset_id": 124
}
```

## Error Handling

Failed jobs include an `error_message` field:

```json
{
  "status": "failed",
  "error_message": "Dataset not found",
  "job": {
    "id": 456,
    "status": "failed",
    "error_message": "Dataset not found"
  }
}
```

## Related Documentation

- [Analysis API](analysis.md)
- [Workers](../workers/index.md)
- [Architecture Overview](../architecture.md)