Jobs API

Monitor, control, and manage job execution

Overview

Jobs represent individual executions of events. Use these endpoints to fetch job details, monitor progress, abort running jobs, and manage job history.

Get Active Jobs

GET /api/app/get_active_jobs/v1

Get all active jobs with optional search criteria, pagination, and sorting.

Parameters

state · string

Filter by state: queued or active

event · string

Filter by event ID

offset · number

Pagination offset (default: 0)

limit · number

Results per page (default: all)

sort_by · string

Sort field (default: started)

sort_dir · number

Sort direction: -1 descending, 1 ascending

Example

cURL

curl -H "X-API-Key: YOUR_API_KEY" \
  "https://your-server.com/api/app/get_active_jobs/v1?state=active&limit=50"

Response

{
  "code": 0,
  "rows": [
    {
      "id": "jabc123",
      "event": "event100",
      "state": "active",
      "progress": 0.5,
      "cpu": 25.5,
      "mem": 128000000
    }
  ],
  "list": { "length": 1 }
}

Get Job

GET /api/app/get_job/v1

Get detailed information about a single job (running or completed).

Parameters

id · string · required

Job ID to fetch

remove · array

Optional array of field names to exclude from response

Response

job · object

Complete job object with all details

token · string

Download token for accessing job log

Example

cURL

curl -H "X-API-Key: YOUR_API_KEY" \
  "https://your-server.com/api/app/get_job/v1?id=jabc123"

Response

{
  "code": 0,
  "token": "abc123def456",
  "job": {
    "id": "jabc123",
    "event": "event100",
    "state": "complete",
    "code": 0,
    "description": "Success",
    "started": 1234567890,
    "completed": 1234567900,
    "elapsed": 10,
    "cpu": { "total": 15.5 },
    "mem": { "max": 128000000 },
    "log_file_size": 4096
  }
}

Get Multiple Jobs

POST /api/app/get_jobs/v1

Fetch information about multiple jobs in a single request.

Parameters

ids · array · required

Array of job IDs to fetch

verbose · boolean

If true, include full details (default: false returns pruned data)

Example

cURL

curl -X POST \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{
    "ids": ["jabc123", "jdef456"],
    "verbose": false
  }' \
  https://your-server.com/api/app/get_jobs/v1

Abort Job

POST /api/app/abort_job/v1

Abort a running job. Requires the abort_jobs privilege.

Parameters

id · string · required

Job ID to abort

Example

cURL

curl -X POST \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{"id": "jabc123"}' \
  https://your-server.com/api/app/abort_job/v1

Response

{
  "code": 0
}

Resume Job

POST /api/app/resume_job/v1

Resume a suspended job. Requires the run_jobs privilege.

Parameters

id · string · required

Job ID to resume

params · object

Optional parameters to merge into job

Example

cURL

curl -X POST \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{
    "id": "jabc123",
    "params": {"continue": true}
  }' \
  https://your-server.com/api/app/resume_job/v1

Delete Job

POST /api/app/delete_job/v1

Permanently delete a completed job including log and files. Requires the delete_jobs privilege.

Parameters

id · string · required

Job ID to delete

Example

cURL

curl -X POST \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{"id": "jabc123"}' \
  https://your-server.com/api/app/delete_job/v1

Deletions are permanent and cannot be undone.

Update Job

POST /api/app/update_job/v1

Update a running or completed job. This is an admin-only API that allows direct modification of job properties.

Parameters

id · string · required

Job ID to update

... · any

Any job properties to update

Example

cURL

curl -X POST \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{
    "id": "jabc123",
    "description": "Custom description"
  }' \
  https://your-server.com/api/app/update_job/v1

Manage Job Tags

POST /api/app/manage_job_tags/v1

Update tags for a completed job. Requires the tag_jobs privilege.

Parameters

id · string · required

Job ID

tags · array · required

Array of tag IDs to assign

Example

cURL

curl -X POST \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{
    "id": "jabc123",
    "tags": ["production", "critical"]
  }' \
  https://your-server.com/api/app/manage_job_tags/v1

Get Job Log

GET /api/app/get_job_log/v1

Fetch the plain text log for a job (gzip compressed).

Parameters

id · string · required

Job ID

Example

cURL

curl -H "X-API-Key: YOUR_API_KEY" \
  "https://your-server.com/api/app/get_job_log/v1?id=jabc123" \
  | gunzip

Download Job Log

GET /api/app/download_job_log/v1

Download job log file with token authentication (no session/API key required).

Parameters

id · string · required

Job ID

t · string · required

Download token from get_job response

Example

cURL

curl "https://your-server.com/api/app/download_job_log/v1?id=jabc123&t=TOKEN" \
  -o job.log.gz

Stream Job

GET /api/app/stream_job/v1

Stream real-time job updates via Server-Sent Events (SSE).

Parameters

id · string · required

Job ID to stream

token · string

Optional stream token (for magic link authentication)

Example

cURL

curl -H "X-API-Key: YOUR_API_KEY" \
  -H "Accept: text/event-stream" \
  "https://your-server.com/api/app/stream_job/v1?id=jabc123"

Event Stream Format

event: start
data: {}

event: update
data: {"id":"jabc123","state":"active","progress":0.25,"cpu":15.5}

event: update  
data: {"progress":0.5,"mem":128000000}

event: update
data: {"code":0,"description":"Success","completed":1234567900}

event: end
data: {}

The stream automatically closes when the job completes.

Flush Event Queue

POST /api/app/flush_event_queue/v1

Flush all queued jobs for an event without triggering completion actions. Requires the abort_jobs privilege.

Parameters

id · string · required

Event ID to flush queue for

Response

count · number

Number of jobs removed from queue

Example

cURL

curl -X POST \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{"id": "event100"}' \
  https://your-server.com/api/app/flush_event_queue/v1