Jobs

The Jobs service is the execution layer for all async operations in cPod — skills, workflows, data source syncs, and cloud asset syncs all produce a Job. You can monitor progress, stream logs, retrieve output, and cancel jobs that are no longer needed.

Most of the time you interact with jobs indirectly through other services. The Jobs API is used directly when you need fine-grained control over polling, cancellation, or output retrieval.


Job Schema

FieldTypeDescription
idstringPrefixed ID: job-{ulid}
typestringWhat produced this job: skill, workflow, sync, cloud_sync
statusenumqueued | running | completed | failed | cancelled
progressnumber0–100 completion percentage
inputobjectInput passed when the job was created
outputobjectResult payload — only set when status = completed
errorobjectError detail — only set when status = failed
startedAtstringISO 8601 UTC
completedAtstringISO 8601 UTC
createdAtstringISO 8601 UTC

Get a Job

import { CpodClient } from '@cpod/sdk'
const sdk = CpodClient.fromEnv()
 
const job = await sdk.jobs.get('job-01HXYZ')
console.log(job.status)    // "running"
console.log(job.progress)  // 42

Wait for Completion

jobs.wait() polls internally with exponential backoff and returns the completed job or throws on failure or timeout.

const result = await sdk.jobs.wait('job-01HXYZ', {
  timeoutMs: 120_000,   // max wait time (default: 60s)
  pollIntervalMs: 2000, // how often to poll (default: 2s)
})
 
if (result.status === 'completed') {
  console.log(result.output)
} else {
  // status === 'failed' — wait() throws by default; use throwOnFailure: false to reach here
  console.error(result.error)
}
 
// Suppress throw on failure
const job = await sdk.jobs.wait('job-01HXYZ', { throwOnFailure: false })

List Jobs

// Recent failed jobs
const failed = await sdk.jobs.list({ status: 'failed', limit: 20 })
for (const job of failed.items) {
  console.log(job.id, job.type, job.error?.message)
}
 
// All skill jobs in the last 24 hours
const skillJobs = await sdk.jobs.list({
  type: 'skill',
  since: new Date(Date.now() - 86_400_000).toISOString(),
})

Cancel a Job

Cancel a queued or running job. Completed jobs cannot be cancelled.

await sdk.jobs.cancel('job-01HXYZ')
 
// Verify
const job = await sdk.jobs.get('job-01HXYZ')
// job.status → "cancelled"

Stream Job Logs

For long-running jobs, stream log lines as they are emitted rather than waiting for completion:

const stream = await sdk.jobs.logs('job-01HXYZ', { follow: true })
 
for await (const line of stream) {
  console.log(`[${line.timestamp}] ${line.level}: ${line.message}`)
}

Job records and logs are retained for 7 days. Long-term audit of job executions should use the Audit Logs service.