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
| Field | Type | Description |
|---|---|---|
id | string | Prefixed ID: job-{ulid} |
type | string | What produced this job: skill, workflow, sync, cloud_sync |
status | enum | queued | running | completed | failed | cancelled |
progress | number | 0–100 completion percentage |
input | object | Input passed when the job was created |
output | object | Result payload — only set when status = completed |
error | object | Error detail — only set when status = failed |
startedAt | string | ISO 8601 UTC |
completedAt | string | ISO 8601 UTC |
createdAt | string | ISO 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) // 42Wait 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.