SDK jobs

The JobManager — reached through ivy.jobs — is how you run computational work: submit a tool, watch its progress, list or cancel jobs, and delete them when done. Reach for it whenever you're driving a compute job from TypeScript, from a fire-and-forget submit() to the all-in-one submitAndWait() that submits and blocks until the job finishes. It sits on the Client you construct first; once a job completes, the Artifacts reference covers downloading its output files.

SDK Jobs Reference

The JobManager handles the full lifecycle of computational jobs: submission, status polling, real-time monitoring, listing, and deletion.

Access via ivy.jobs.

jobs.submit(params)

Submit a new computational job. Returns immediately with the job ID.

async submit(params: SubmitJobParams): Promise<{
  id: string
  status: string
  taskId?: string
}>

Parameters:

Returns:

Throws: IvyApiError on validation (422), auth (401/403), or server (5xx) errors.

Examples

const { id, taskId } = await ivy.jobs.submit({
  toolName: "esmfold",
  parameters: { protein_sequence: "MKFLILLFNILCLFPVLAADNH" },
  analysisLevel: "comprehensive",
})
console.log(`Job ${id} submitted (task: ${taskId})`)

jobs.getStatus(jobId)

Get the current status of a job. Lightweight endpoint suitable for polling.

async getStatus(jobId: string): Promise<JobProgress>

Parameters:

Returns: JobProgress — current status, progress %, phase, and results.

Throws: IvyApiError with isNotFound if the job doesn't exist.

Examples

let status = await ivy.jobs.getStatus("job_abc123")
while (status.status !== "COMPLETED" && status.status !== "FAILURE") {
  await new Promise(r => setTimeout(r, 3000))
  status = await ivy.jobs.getStatus("job_abc123")
}
console.log(status.result)

jobs.getDetails(jobId)

Get full job details including parameters, timestamps, and metadata.

async getDetails(jobId: string): Promise<Record<string, unknown>>

More expensive than getStatus — use for detailed inspection, not polling.

Throws: IvyApiError with isNotFound if the job doesn't exist.

Examples

const details = await ivy.jobs.getDetails("job_abc123")
console.log(details.created_at, details.tool_name, details.analysis_level)

jobs.list(options?)

List the authenticated user's jobs with pagination.

async list(options?: { skip?: number; limit?: number }): Promise<Record<string, unknown>[]>

Parameters:

Returns: Array of job records, ordered by creation time (newest first).

Examples

const jobs = await ivy.jobs.list({ limit: 10 })
for (const job of jobs) {
  console.log(`${job.id}: ${job.status} (${job.tool_name})`)
}

jobs.delete(jobId)

Delete a job and its associated S3 artifacts. Irreversible.

async delete(jobId: string): Promise<void>

Throws:

• IvyApiError with isNotFound if the job doesn't exist.
• IvyApiError with isForbidden if the job belongs to another user.

Examples

await ivy.jobs.delete("job_abc123")

Cancelling a job

JobManager has no cancel method. In React, the cancel function returned by useIvyJob stops the hook tracking the job on the client; it does not stop the job on the backend. To remove a job, use jobs.delete.

jobs.submitAndWait(params, options?)

Submit a job and wait for it to reach a terminal state. The highest-level convenience method.

async submitAndWait(
  params: SubmitJobParams,
  options?: SubmitAndWaitOptions,
): Promise<JobProgress>

Strategy:

1. Submits the job via HTTP POST
2. Subscribes to WebSocket updates (if useWebSocket is true)
3. Falls back to HTTP polling if WebSocket fails
4. Resolves when status is COMPLETED, FAILURE, or CANCELLED

Options:

Returns: Final JobProgress with status, results, and/or errors.

Throws:

• IvyTimeoutError if the job doesn't finish within the timeout.
• IvyApiError on submission or polling errors.

Examples

const result = await ivy.jobs.submitAndWait(
  {
    toolName: "diffdock",
    parameters: { protein_pdb: "...", ligand_smiles: "CCO" },
  },
  {
    onProgress: (p) => console.log(`[${p.phase}] ${p.progress}%`),
    timeout: 300_000, // 5 minutes
  }
)

if (result.status === "COMPLETED") {
  const pdbUrl = result.presignedUrl
  // Download the docked structure...
}

Job Lifecycle

Standard Phases

Analysis Levels