Jobs

A job is a single execution of a worker with a specific input payload. Jobs are asynchronous — triggering one returns immediately with a job record; execution happens in the background.

Trigger a job

bash

POST /v1/ava/jobs

Name	Type	Required	Description
worker_id	string	Yes	ID of the worker to run.
input	object	No	Payload passed to the worker handler as the first argument.
trigger	string	No	manual \| scheduled \| webhook \| event. Defaults to "manual".
priority	integer	No	1 (highest) to 10 (lowest). Default 5. High-priority jobs are dequeued first.
scheduled_at	string	No	ISO 8601 datetime to delay execution until. Omit for immediate queuing.

bash

curl -X POST https://api.hldgroup.org/v1/ava/jobs \
  -H "x-internal-secret: <key>" \
  -H "x-tenant-id: ten_01hxyz" \
  -H "x-user-id: usr_01hxyz" \
  -H "x-platform-role: tenant-system-admin" \
  -H "Content-Type: application/json" \
  -d '{
    "worker_id": "wkr_01hxyz",
    "priority": 2,
    "input": {
      "incident_id": "inc_01hxyz",
      "channel": "#security-ops"
    }
  }'

json

{
  "data": {
    "id": "job_01hxyz",
    "worker_id": "wkr_01hxyz",
    "tenant_id": "ten_01hxyz",
    "status": "queued",
    "trigger": "manual",
    "priority": 2,
    "input": { "incident_id": "inc_01hxyz", "channel": "#security-ops" },
    "triggered_by": "usr_01hxyz",
    "created_at": "2025-06-01T10:00:00Z",
    "started_at": null,
    "completed_at": null,
    "duration_ms": null,
    "output": null,
    "error": null
  }
}

Poll job status

bash

GET /v1/ava/jobs/:id

Poll until status is completed, failed, or cancelled. The output field contains the return value from your handler function. error contains the failure reason.

List jobs

bash

GET /v1/ava/jobs

Name	Type	Required	Description
filter[worker_id]	string	No	Filter to a specific worker.
filter[status]	string	No	queued \| running \| completed \| failed \| cancelled
filter[trigger]	string	No	manual \| scheduled \| webhook \| event
filter[created_after]	string	No	ISO 8601 lower bound.
filter[created_before]	string	No	ISO 8601 upper bound.

View job logs

bash

GET /v1/ava/jobs/:id/logs

Name	Type	Required	Description
filter[level]	string	No	info \| warn \| error
limit	integer	No	Max log lines to return. Default 100, max 500.

json

{
  "data": {
    "job_id": "job_01hxyz",
    "job_status": "completed",
    "logs": [
      { "ts": "2025-06-01T10:00:01.120Z", "level": "info",  "msg": "Worker handler started" },
      { "ts": "2025-06-01T10:00:01.430Z", "level": "info",  "msg": "Fetching incident inc_01hxyz" },
      { "ts": "2025-06-01T10:00:02.891Z", "level": "info",  "msg": "Slack message sent: 1717200000.000100" },
      { "ts": "2025-06-01T10:00:02.900Z", "level": "info",  "msg": "Handler completed in 1780ms" }
    ]
  }
}

Cancel a job

bash

POST /v1/ava/jobs/:id/cancel

Only queued or running jobs can be cancelled. Cancelling a running job sends SIGTERM to the worker process — your handler should listen for this and clean up gracefully.

Tip:Subscribe to ava.job.completed and ava.job.failed webhook events to react in real time without polling. The event payload includes the full job record including output and error.

Schedules Analytics