Skip to main content

​
Overview

Jobs are background tasks that process project data. Common job types include packaging projects for field use, applying deltas, and processing QGIS project files.

​
List Jobs

curl -X GET "https://app.qfield.cloud/api/v1/jobs/?project_id={project_id}" \
  -H "Authorization: Token YOUR_TOKEN"
GET /api/v1/jobs/ List all jobs for a specific project.

​
Query Parameters

​
project_id
uuid
required
The unique identifier of the project
​
limit
integer
Number of results to return per page
​
offset
integer
The initial index from which to return the results

​
Response

​
count
integer
Total number of jobs
​
next
string
URL to the next page of results
​
previous
string
URL to the previous page of results
​
results
array
Array of job objects
​
id
uuid
Unique job identifier
​
type
string
Job type: package, delta_apply, or process_projectfile
​
status
string
Job status: pending, queued, started, stopped, finished, or failed
​
project_id
uuid
ID of the project this job belongs to
​
created_by
string
Username of the user who created the job
​
created_at
datetime
When the job was created
​
updated_at
datetime
When the job was last updated
​
started_at
datetime
When the job started processing
​
finished_at
datetime
When the job finished
{
  "count": 2,
  "next": null,
  "previous": null,
  "results": [
    {
      "id": "9h0g1f32-4e5d-6c7e-g8h9-001122334455",
      "type": "package",
      "status": "finished",
      "project_id": "550e8400-e29b-41d4-a716-446655440000",
      "created_by": "john_doe",
      "created_at": "2026-03-04T10:00:00Z",
      "updated_at": "2026-03-04T10:05:00Z",
      "started_at": "2026-03-04T10:00:30Z",
      "finished_at": "2026-03-04T10:05:00Z"
    },
    {
      "id": "0i1h2g43-5f6e-7d8f-h9i0-112233445566",
      "type": "delta_apply",
      "status": "finished",
      "project_id": "550e8400-e29b-41d4-a716-446655440000",
      "created_by": "field_user",
      "created_at": "2026-03-04T09:31:00Z",
      "updated_at": "2026-03-04T09:32:15Z",
      "started_at": "2026-03-04T09:31:10Z",
      "finished_at": "2026-03-04T09:32:15Z"
    }
  ]
}

​
Get Job

curl -X GET "https://app.qfield.cloud/api/v1/jobs/{job_id}/" \
  -H "Authorization: Token YOUR_TOKEN"
GET /api/v1/jobs/{job_id}/ Retrieve details of a specific job, including detailed output and feedback.

​
Path Parameters

​
job_id
uuid
required
The unique identifier of the job

​
Response

​
id
uuid
Unique job identifier
​
type
string
Job type: package, delta_apply, or process_projectfile
​
status
string
Job status: pending, queued, started, stopped, finished, or failed
​
project_id
uuid
ID of the project this job belongs to
​
created_by
string
Username of the user who created the job
​
created_at
datetime
When the job was created
​
updated_at
datetime
When the job was last updated
​
started_at
datetime
When the job started processing
​
finished_at
datetime
When the job finished
​
output
string
Job output messages and logs
​
feedback
object
Detailed feedback object with job results and errors
{
  "id": "9h0g1f32-4e5d-6c7e-g8h9-001122334455",
  "type": "package",
  "status": "finished",
  "project_id": "550e8400-e29b-41d4-a716-446655440000",
  "created_by": "john_doe",
  "created_at": "2026-03-04T10:00:00Z",
  "updated_at": "2026-03-04T10:05:00Z",
  "started_at": "2026-03-04T10:00:30Z",
  "finished_at": "2026-03-04T10:05:00Z",
  "output": "Package job completed successfully\nProcessed 3 layers\nTotal size: 15.2 MB",
  "feedback": {
    "feedback_version": "2.0",
    "outputs": {
      "qgis_layers_data": {
        "layers_by_id": {
          "trees_layer": {
            "id": "trees_layer",
            "name": "Trees",
            "is_valid": true,
            "feature_count": 1523
          }
        }
      }
    }
  }
}

​
Create Job

curl -X POST "https://app.qfield.cloud/api/v1/jobs/" \
  -H "Authorization: Token YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "package",
    "project_id": "550e8400-e29b-41d4-a716-446655440000"
  }'
POST /api/v1/jobs/ Create a new background job.

​
Request Body

​
type
string
required
Job type: package, delta_apply, or process_projectfile
​
project_id
uuid
required
The unique identifier of the project
​
force
integer
Force creating the job even if a similar job is already running. Set to 1 to force. Default: 0

​
Job Types

​
Package Job

Packages the project for field use in QField. This creates an optimized version of the project data.
  • Type: package
  • Allows parallel jobs: No (unless force=1)
  • Requirements: Project must contain a QGIS project file (.qgs or .qgz)

​
Delta Apply Job

Applies pending deltas (changes) to the project data.
  • Type: delta_apply
  • Allows parallel jobs: Yes
  • Requirements: Project must contain a QGIS project file

​
Process Projectfile Job

Processes and validates the QGIS project file.
  • Type: process_projectfile
  • Allows parallel jobs: Yes
  • Requirements: Project must contain a QGIS project file

​
Response

Returns the created job object. If a similar job is already running and force=0, returns the existing job instead of creating a new one. 
{
  "id": "1j2i3h54-6g7f-8e9g-i0j1-223344556677",
  "type": "package",
  "status": "pending",
  "project_id": "550e8400-e29b-41d4-a716-446655440000",
  "created_by": "john_doe",
  "created_at": "2026-03-04T12:00:00Z",
  "updated_at": "2026-03-04T12:00:00Z",
  "started_at": null,
  "finished_at": null
}

​
Error Responses

{
  "code": "no_qgis_project",
  "message": "Project must contain a QGIS project file (.qgs or .qgz)"
}

​
Job Statuses

Jobs progress through the following statuses:
  • pending: Job is waiting to be queued
  • queued: Job is in the queue waiting for a worker
  • started: Job is currently being processed
  • stopped: Job was stopped before completion
  • finished: Job completed successfully
  • failed: Job failed with an error

​
Job Types Reference

​
Package Job

Packaging jobs prepare the project for offline use in QField:
  • Validates all layers
  • Optimizes data for mobile devices
  • Generates layer metadata
  • Creates attachment references

​
Delta Apply Job

Delta apply jobs synchronize field changes:
  • Applies pending deltas in order
  • Detects and handles conflicts
  • Updates feature attributes and geometries
  • Maintains data integrity

​
Process Projectfile Job

Projectfile processing jobs:
  • Parse QGIS project XML
  • Validate layer configurations
  • Check data source availability
  • Extract layer metadata

Build docs developers (and LLMs) love

Get started for freeTalk to us