---
title: Jobs REST API
description: 'Submit, poll, list, cancel and rerun computational biology jobs via the REST API'
tags:
  - rest
  - jobs
  - submit
  - poll
---
The Jobs API is how you run computational biology tools — protein structure prediction, molecular docking, ADMET analysis, and more — over HTTP. Reach for it when you want to submit a job, poll it to completion, and pull back results from your own server, CLI, or CI pipeline. The public [guest orchestrator](/docs/api#guest-curl) is the no-account entry point; authenticated job routes add persistence and account-scoped history. This page is the primary building block that sibling pages extend: [Batch Jobs](/docs/api/rest-batch) fan one tool out across many inputs, and [Artifacts & Storage](/docs/api/rest-artifacts) handles downloading the outputs a completed job produces.

  beginner
  15 min
  [authentication](/docs/api/authentication)

## Jobs API

Submit, monitor, and manage computational biology jobs. A submitted job runs on the compute backend; the web app records it against your account and forwards status back to you.

**Base URL:** `https://www.ivybiosciences.com/api`

Every route takes `Authorization: Bearer ivy_...` (or a Clerk JWT) unless its reference page says otherwise. The `ivybloom` [CLI](/docs/cli) wraps the same operations (`ivybloom jobs ...`).

> **Try it live:** Open the [Interactive API Reference](/docs/api/reference) to test these endpoints directly from your browser.

---

## Submit Job

`POST /api/v1/jobs` ([reference](/docs/api/reference/post-api-v1-jobs)) takes `tool_name` and `tool_input_parameters`, plus optional `project_id`, `job_title` and `chat_id`.

```bash
curl -X POST https://www.ivybiosciences.com/api/v1/jobs \
  -H "Authorization: Bearer ivy_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "tool_name": "esmfold",
    "tool_input_parameters": {"protein_sequence": "MKFLILLFNILCLFPVLAADNH"},
    "job_title": "ESMFold test"
  }'
```

The response carries the new job's `id` and its initial `status` (`PENDING`).

---

## Get Job Status

`GET /api/v1/jobs/:jobId` ([reference](/docs/api/reference/get-api-v1-jobs-job-id)) returns the current status and progress along with the rest of the record. To follow a job without polling, use the [SSE job stream](/docs/api/realtime-sse#job-event-proxy-sse).

---

## Get Job Details

`GET /api/v1/jobs/:jobId` ([reference](/docs/api/reference/get-api-v1-jobs-job-id)) returns the full job record, including the results and output artifact references of a finished job. `GET /api/v1/jobs/batch?ids=...` ([reference](/docs/api/reference/get-v1-jobs-batch)) reads several jobs in one call. To download a finished job's files, `GET /api/v1/jobs/:jobId/artifacts` ([reference](/docs/api/reference/get-v1-jobs-jobid-artifacts)) returns short-lived download links; see [Artifacts & Storage](/docs/api/rest-artifacts).

---

## List Jobs

`GET /api/v1/jobs` ([reference](/docs/api/reference/get-api-v1-jobs)) returns your jobs, 15 per page by default. Filter with `projectId`, `status`, `type`, `q`, `start` and `end`; page with `page` and `pageSize`.

---

## Cancel or Rerun a Job

`POST /api/v1/jobs/:jobId/cancel` ([reference](/docs/api/reference/post-v1-jobs-jobid-cancel)) cancels a job that has not finished. `POST /api/v1/jobs/:jobId/resubmit` ([reference](/docs/api/reference/post-v1-jobs-jobid-resubmit)) runs a job again as a new job, optionally with changed parameters. `GET /api/v1/jobs/pricing` ([reference](/docs/api/reference/get-v1-jobs-pricing)) lists the credit price of each tool before you submit.

---

## Job Lineage

`GET /api/v1/jobs/:jobId/lineage` ([reference](/docs/api/reference/get-v1-jobs-jobid-lineage)) lists which job outputs fed a job you can read: one row per producer output, with the producer job, the output and the input slot it filled. A row includes the output's data type and preview only when you can read the producer job. `POST /api/v1/jobs/:jobId/lineage` ([reference](/docs/api/reference/post-v1-jobs-jobid-lineage)) records those sources for a job you can write to; every producer job must be one you can read, and every output must belong to its producer job, or nothing is recorded.

```bash
curl -X POST https://www.ivybiosciences.com/api/v1/jobs/<job_id>/lineage \
  -H "Authorization: Bearer ivy_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "sources": [
      {"producer_job_id": "<producer_job_id>", "producer_output_id": "<output_id>", "input_slot": "protein_structure"}
    ]
  }'
```

## Plates, readouts and other per-job data

The plate, readout and QC data you see on a job in the app is also under `/api/v1/jobs/{jobId}/`, with the same API key and the same access rules as the app: a project viewer can read a job's data but not change it, `extract/pdb` and `extract/sdf` serve only the job's owner, and a key scoped to some projects reaches only jobs in those projects. On most routes a job you cannot reach returns 404, the same as a job that does not exist; the reference gives each route's responses.

- **Plate:** read and save wells (`plate`), save the plate type (`plate-config`), list plate types (`plate-types`), undo the last plate update (`undo`).
- **Readouts and QC:** read and save readouts (`readouts`), upload a readout file (`readouts/upload`), read QC (`qc`, `qc/metrics`).
- **Dose-response:** fit curves (`fit-curves`), read stored fits (`curve-fits`).
- **Candidates and ordering:** study candidates (`candidates`), procurement items (`procurement`).
- **Results and downloads:** a result file's summary or raw text (`artifact-content`), which follow-up exports a job supports (`context`), a download link for one file by type (`download/{artifactType}`, including the generated `fits`, `qc` and `procurement` files) and the plate map CSV (`download/plate-map`).
- **Files and records:** a PDB or SDF from the job's ZIP output (`extract/pdb`, `extract/sdf`), extracted files (`extractions`), checkpoints (`checkpoints`), snapshots (`snapshots/list`), the latest manifest (`manifest/latest`, `manifest/fetch`), and SHA-256 checks of output files (`artifacts/verify`, `artifacts/list-verifications`).

Each route's parameters, bodies and responses are in the [API reference](/docs/api/reference).

```bash
curl https://www.ivybiosciences.com/api/v1/jobs/<job_id>/readouts \
  -H "Authorization: Bearer ivy_your_key"
```

---

## Job Lifecycle

 STARTED
    STARTED --> PROCESSING
    PROCESSING --> COMPLETED
    PROCESSING --> FAILURE
    PROCESSING --> CANCELLED
    PROCESSING --> SUCCESS
    PROCESSING --> PROGRESS : repeated
    state "ARCHIVED (soft-deleted by retention policy)" as ARCHIVED
    state "IMPORTED (migrated from guest to authenticated)" as IMPORTED`}
  caption="Job status lifecycle, plus the ARCHIVED and IMPORTED states."
/>

### Full Status Enum

| Status | Description |
|--------|-------------|
| `PENDING` | Queued for execution |
| `STARTED` | Container provisioned, initializing |
| `PROCESSING` | Main computation running |
| `PROGRESS` | Intermediate update (may repeat) |
| `SUCCESS` | Alias for COMPLETED (some tools) |
| `COMPLETED` | Finished successfully; results available |
| `FAILURE` | Fatal error |
| `CANCELLED` | Cancelled by user |
| `ARCHIVED` | Soft-deleted by retention policy |
| `IMPORTED` | Migrated from another system |

## Read next

- [Batch Jobs](/docs/api/rest-batch) — fan-out parallel job submission
- [Job Types Catalog](/docs/api/job-types) — the tools you can submit
- [Artifacts & Storage](/docs/api/rest-artifacts) — download job outputs
- [SSE Streaming](/docs/api/realtime-sse#job-event-proxy-sse) — real-time status updates
- [SDK Jobs](/docs/api/sdk-jobs) — TypeScript SDK wrapper