Bulk to Single Cell API
BETAOverview
Submit a compatible bulk RNA-seq count matrix to estimate cell-type proportions for each sample and generate model-conditioned expression. Select a model appropriate for your sample context. Outputs are computational predictions for research use.
What you get back
One row per sample per cell type, summing to 1.000 within a sample. Long or wide. This is the primary result and what most integrations consume.
An .h5ad matrix of 1,000 generated cells per sample over the model's 2,000-gene panel, consistent with those proportions — readable by scanpy/anndata in Python or Seurat in R. The values are continuous BCS-corrected generated expression; not measured or integer counts.
Which release and model produced the result, the seed, the cells per sample, the engine code version and image digest, and a verification report — records needed to investigate the run and attempt reproduction under its documented conditions.
Quickstart
Submit a reference run using the reference input that ships beside each model release. Nothing to upload and nothing to prepare — run this first to prove your key works and to see the shape of what comes back.
pip install 'wittgen-b2sc[pandas]' # the [pandas] extra is what as_dataframe=True below needs
from wittgen_b2sc import B2SCClient
client = B2SCClient(api_key="wgk_…")
job = client.submit_job(disease_model="breast-tumour-2k-v2", source="reference_dataset")
client.wait_for_completion(job["job_id"]) # polls for you
df = client.get_proportions(job["job_id"], as_dataframe=True)
print(df.head())
# sample cell_type proportion
# 0 CID3586 B-cells 0.028853
# 1 CID3586 Cancer Epithelial 0.224694
# 2 CID3586 Cycling T-cells 0.043717Check your key before anything else
curl -H "Authorization: Bearer $WITTGEN_API_KEY" https://www.wittgenbio.com/api/v1/b2sc/models
# 200 -> your key works, and you get the model catalogue
# 401 -> the key is missing, malformed or revokedRead a published cohort
An atlas is a cohort we have already run, owned by a system account and readable by every key — every read endpoint accepts its job id, so anything you learn on one transfers directly to your own jobs.
Atlases are readable by every account and writable by none.
curl -H "Authorization: Bearer $WITTGEN_API_KEY" https://www.wittgenbio.com/api/v1/b2sc/atlasesThe same call you will make on your own job.
df = client.get_proportions("<atlas job id>", as_dataframe=True)
print(df.shape) # (samples x cell types, 3)Sample count, the cell-type axis, the seed and cells per sample, and the input contract the run was held to.
rd = client.get_results_data("<atlas job id>")
print(rd["metadata"]["n_samples"], rd["metadata"]["release_id"])Run your own cohort
Upload is two steps: ask for a presigned S3 URL, then send the bytes straight to S3. The object is uploaded directly rather than as the API request body. Service file-size, upload-validity and validation limits still apply. The SDK wraps both steps; the raw form is shown too because the PUT has a detail that will otherwise cost you an afternoon.
Prepare the matrix
| Requirement | Detail |
|---|---|
| Orientation | First column is the gene identifier; every other column is one sample. First row is the sample names. |
| Identifiers | Use the model's identifier spelling — download the common axis and fixed panel from GET /b2sc/models/{id}/required-genes. Two of the three lists mix HGNC symbols and Ensembl ids, gene by gene. The model matches them verbatim; every upload, gzipped or not, is first prepared with the release's frozen dictionaries (Ensembl version suffix, approved symbol to Ensembl id pairing, no inferred aliases): identifiers are renamed and every rename is recorded on the job, every row is kept, and two rows that land on one gene are refused (INPUT_DUPLICATE_GENE_AFTER_MAPPING), never summed. Missing common and panel genes are reported; the service prepares absent rows as zero under platform-zero-pad-v1. Submit the full available matrix and review the warning rather than manually filling or filtering it. |
| Values | Raw counts or quantifier expected counts with source provenance. Normalized or log-transformed input is incompatible; review the input contract. |
| Samples | One job runs at most 64 (cohort.batch_size on GET /b2sc/models). A wider matrix is split into batches for you where cohort.enabled is true, up to cohort.max_samples; where it is false the submission is refused with COHORT_TOO_MANY_SAMPLES and you split it yourself — see the batching tutorial. |
| Format | .tsv .csv .txt, each optionally gzipped. Supported file extensions; use the same input contract for each. |
key = client.upload_file("my_cohort.tsv.gz") # presign, PUT, wait until verified
job = client.submit_job("breast-tumour-2k-v2", source="user_upload", input_file_key=key)
client.wait_for_completion(job["job_id"])
df = client.get_proportions(job["job_id"], as_dataframe=True)Check the gene list before you upload
The dashboard does this for you in the browser before a byte is uploaded. From code, fetch the list once per model — it is immutable per release and the response says so with an ETag — and take the set difference yourself:
import pandas as pd, requests
required = requests.get(
"https://www.wittgenbio.com/api/v1/b2sc/models/breast-tumour-2k-v2/required-genes",
headers={"Authorization": f"Bearer {API_KEY}"},
).json()["genes"] # 16,864 identifiers for this model
m = pd.read_csv("my_cohort.tsv.gz", sep="\t", index_col=0)
missing = [g for g in required if g not in m.index]
print(len(missing), missing[:20]) # Review missing common genes; service records zero-paddingRun a cohort larger than 64 samples
One job runs at most 64 samples. GET /b2sc/models publishes what a submission may carry as cohort: { enabled, batch_size, max_samples }. With enabled true, a wider matrix up to max_samples is accepted and split into batches of batch_size for you, and the job reports cohort: true with n_samples. With enabled false, max_samples equals batch_size and a wider matrix is refused at submit with COHORT_TOO_MANY_SAMPLES — split it into batches, submit one job each and concatenate. Every batch of one model returns the same cell-type columns in the same order, which is what makes that safe.
import pandas as pd
m = pd.read_csv("cohort_300.tsv", sep="\t", index_col=0) # genes x samples
batches = [m.iloc[:, i:i + 64] for i in range(0, m.shape[1], 64)]
jobs = []
for n, b in enumerate(batches):
path = f"batch{n:02d}.tsv.gz"
b.to_csv(path, sep="\t", compression="gzip")
key = client.upload_file(path)
jobs.append(client.submit_job("breast-tumour-2k-v2",
source="user_upload", input_file_key=key)["job_id"])
frames = []
for jid in jobs:
client.wait_for_completion(jid)
frames.append(client.get_proportions(jid, as_dataframe=True))
# Safe to concatenate: every batch returns the same cell types in the same order.
all_props = pd.concat(frames, ignore_index=True)Run a verified GEO series
Name a verified accession instead of uploading a file and the server fetches the series, picks the count matrix out of its supplementary listing, and runs it. The list is short on purpose: it holds the series we have actually run against the current release, not the ones that look like they would.
The verified series
job = client.submit_job("t-all-2k-v2", source="geo", geo_accession="GSE000000")
# -> B2SCError GEO_SERIES_NOT_VERIFIED_FOR_MODEL until the accession is on the list for this model;
# inspect the response for the current verification state.When it refuses, and why that is the point
Wire it into an unattended pipeline
What changes when nobody is watching: submissions must be safe to retry, polling must have a ceiling, and a failure has to be distinguishable from a delay.
Make the submission safe to retry
A submission is a GPU run and a metered unit, so a duplicate is a second charge for work you already asked for. The realistic cause is not a careless client but an ordinary network timeout: the request arrives, the response does not. Send an Idempotency-Key and a retry returns the SAME job instead of starting another.
curl -X POST https://www.wittgenbio.com/api/v1/b2sc/jobs \
-H "Authorization: Bearer $WITTGEN_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"disease_model":"breast-tumour-2k-v2","source":"reference_dataset"}'| Replaying a key | Response |
|---|---|
| The job exists | 200 with that job — no second run, no quota consumed |
| Still being accepted | 202 IDEMPOTENT_REQUEST_IN_FLIGHT with the reserved job_id — wait Retry-After seconds, repeat with the same key |
| The job was deleted | 409 IDEMPOTENT_JOB_GONE — use a new key |
| Malformed key | 400 INVALID_IDEMPOTENCY_KEY — printable ASCII, no spaces, ≤200 chars |
Generate the key yourself and keep it with the retry — a UUID is the obvious choice. Its scope is your account, so two accounts may use the same value without colliding, and it is forgotten after 24 hours.
Poll with a ceiling, and stop on terminal states only
import time
def wait(job_id, timeout=10800, interval=15):
deadline = time.monotonic() + timeout
while True:
job = client.get_job(job_id)
if job["status"] == "COMPLETED":
return job
if job["status"] == "FAILED":
# message is written for a person and says what to change
raise RuntimeError(f"{job_id}: {job['message']}")
if time.monotonic() > deadline:
raise TimeoutError(f"{job_id} still {job['status']}")
time.sleep(interval)Know which failures are worth retrying
| Kind | Examples | Retry? |
|---|---|---|
| Your input | INVALID_MODEL, GENE_IDS_MUST_BE_SYMBOLS, UNSUPPORTED_FILE_TYPE, FILE_TOO_LARGE, GEO_NO_RAW_COUNTS, INPUT_DUPLICATE_GENE, INPUT_DUPLICATE_GENE_AFTER_MAPPING, INPUT_NEGATIVE_VALUE, INPUT_RAW_COUNT_REQUIRED | No — fix and resubmit |
| Ambiguity we refuse to resolve | GEO_AMBIGUOUS | No — re-submit naming the file |
| Your budget | RATE_LIMITED, RAW_DOWNLOAD_BUDGET_EXCEEDED | Yes — after the window rolls |
| Ours | 5xx, 503 MODEL_NOT_PROVISIONED | Yes — with backoff. Send the job id if it persists |
Before you send anything
Admission checks can reject incompatible input before queueing. Numeric checks alone cannot establish units or scientific validity. Confirm units and sample context from source provenance, and review returned input warnings.
When admission can complete, the submission API checks the matrix before queueing and the engine repeats validation. Negative values, fixed-library normalized values and ambiguous identifiers can be refused. Fractional values alone are not refused: expected counts can be fractional. Read input_warnings and confirm units from source provenance; a numeric screen cannot reliably identify every transformed matrix.
| Model | Cell types | Applies to | Not for |
|---|---|---|---|
| breast-tumour-2k-v2 | 11 | Human breast tumour tissue, bulk RNA-seq of the whole tumour including its microenvironment, raw counts. | Blood, normal breast, other tumour types, cell lines or non-human samples. |
| t-all-2k-v2 | 10 | Human T-ALL bone marrow or peripheral blood, bulk RNA-seq, raw counts. | Solid tissue, other leukaemias, cell lines or non-human samples. |
| sepsis-pbmc-2k-v1 | 10 | Human PBMC from sepsis cohorts, bulk RNA-seq, raw counts. | Whole blood with granulocytes, solid tissue, cell lines or non-human samples. The reference is PBMC, so neutrophil-rich whole blood will be described against an axis that under-represents it. |
Each model reports its own ordered cell-type axis, and every run returns that axis as cell_types on GET /b2sc/jobs/{id}/proportions — runs of one model under one release line up column for column; runs of different models do not share a vocabulary at all.
| Model | Cell-type axis, in column order |
|---|---|
| breast-tumour-2k-v2 | B-cells · Cancer Epithelial · Cycling T-cells · Endothelial · Fibroblast · Myeloid · NK · Normal Epithelial · PVL · Plasmablasts · T cells |
| t-all-2k-v2 | ALL blast · B · Classical Monocyte · Cytotoxic T · DC · Erythroid · FCGR3A+ Monocyte · HSC · NKT · naive/Tcm |
| sepsis-pbmc-2k-v1 | T_cell · Monocyte · B_cell · NK_cell · Erythroid · Platelet · Plasma · Neutrophil · DC · HSPC |
3. The gene list is exact
Keep the full available raw matrix rather than selecting only the output genes. The engine uses a fixed common-gene axis for Stage1 normalization, then selects its fixed 2,000-gene panel. The service input policy platform-zero-pad-v1 reports missing common and panel genes and prepares absent rows as zero before inference. This is an assumption about missing values, not recovered measurements or an accuracy guarantee. No HVGs are reselected.
| Model | model_id (engine alias) | Fixed panel | Common axis | The list |
|---|---|---|---|---|
| breast-tumour-2k-v2 | iclr27-pbe-bcs-GSE176078 | 2,000 | 16,864 | GET /b2sc/models/breast-tumour-2k-v2/required-genes |
| t-all-2k-v2 | iclr27-pbe-bcs-SCPCP000003 | 2,000 | 55,719 | GET /b2sc/models/t-all-2k-v2/required-genes |
| sepsis-pbmc-2k-v1 | iclr27-pbe-bcs-GSE279448_GSE279452_sepsis_PBMC | 2,000 | 40,200 | GET /b2sc/models/sepsis-pbmc-2k-v1/required-genes |
A job record carries both identifiers: disease_model is the id you submitted, model_id is the engine alias the release knows the model by. Together with release_id they say exactly which weights produced a result.
{
"kind": "exact_common_genes",
"required_genes": 16864,
"satisfied": true
}input_contract describes the engine axis after preparation; it does not prove that every gene was measured in the submitted matrix. Read metadata.input_preparation for the policy version, missing common and panel counts, and whether zero-padding occurred. Historical or not-yet-screened records may have no preparation details. Successful inference does not establish biological validity.
User-facing expression follows platform-observed-panel-v1: the ordered output axis is the fixed model panel intersected with the original input gene IDs after supported mapping. Observed zero-count input rows remain included. Input-absent panel genes are excluded even if their generated values are nonzero. This does not change internal zero-padding, fixed-panel inference, proportions or cell allocations, and does not generate genes outside the model panel.
For partial panel coverage, default expression NPZ and H5AD pointers select separate input-observed artifacts; the original model NPZ, H5AD and run manifest remain unchanged. Full panel coverage creates no additional artifacts. metadata.output_projection reports policy_version, model_gene_count, returned_gene_count, excluded_input_genes (the number of panel genes excluded because they were absent from the input), and returned_axis_sha256. Historical results may have no projection record and are not rewritten. All retained and additional files remain subject to the admitted storage envelope.
{
"policy_version": "platform-zero-pad-v1",
"missing_common_genes": 3,
"missing_panel_genes": 1,
"zero_padding": true
}How a job runs
Submit, poll, collect. A job moves through status until it reaches COMPLETED, FAILED or CANCELLED — all three terminal, and the only values a client should stop on.
| status | Meaning | Terminal |
|---|---|---|
| PENDING | Accepted, not yet queued. | |
| AWAITING_CREDIT | Accepted; waiting for the credit or contract approval that lets it start. | |
| SPLITTING | A large cohort is being divided into batches. | |
| QUEUED | Waiting for a GPU. | |
| LAUNCHING | A GPU task is starting. Includes image pull on a cold node. | |
| DOWNLOADING_INPUT | Fetching your matrix. | |
| LOADING_MODEL | Verifying the model release by hash and loading its weights. | |
| RUNNING_STAGE1 | Predicting cell-type proportions. | |
| RUNNING_STAGE2 | Generating single cells: PBE (the patient-bulk encoder, a generator conditioned on each sample's own bulk profile), then BCS (a bulk-consistency correction of the generated expression). | |
| UPLOADING_RESULTS | Verifying the output contract and writing the result files. | |
| COMPLETED | Proportions and generated cells are ready. | terminal |
| FAILED | See message — written for a person, and it says what to change. | terminal |
| CANCELLED | Stopped before all of it ran: withdrawn by you or an administrator before it reached a GPU, or it could not start in time. A single job that is CANCELLED ran nothing and was not charged. A cohort can be CANCELLED after some of its batches finished; then outcome is partially_completed, and those batches are charged and their results are delivered (see below). | terminal |
A cohort that was partly completed
A cohort is split into batches of 64 samples. If it is CANCELLED after some batches finished, GET /b2sc/jobs/{id} adds outcome: "partially_completed", batch_count, completed_batches and charged_batches (only finished batches can be charged, so the two counts are equal; a finished batch whose usage cannot be verified is released instead), and a batches list. Each entry has a job_id, batch_index, sample_start and sample_end (1-based, inclusive, in the order of your file's sample columns), n_samples, and a status: COMPLETED, FAILED or NOT_RUN. Collect each COMPLETED batch with its own job_id through GET /b2sc/jobs/{batch id}/result, /files and /proportions. To analyse the FAILED and NOT_RUN samples, submit them again. outcome: "cancelled" means no batch finished and nothing was charged; "unknown" means the batches could not be read just now, so retry the read. A list response carries the counts but not the batches. These fields appear only on a CANCELLED cohort.
A completed cohort: generated cells per batch
A COMPLETED cohort (more than 64 samples) has one proportions.csv and one cell_counts.csv covering every sample, but its generated cells are delivered per batch of up to 64 samples. GET /b2sc/jobs/{id}/files?include_raw=1 lists one generated_cells.batchNN.samplesA-B.h5ad per batch. Each entry carries batch: job_id, batch_index, sample_start, sample_end (1-based, inclusive, in the order of your file's sample columns) and n_samples. One raw-download budget entry covers the whole listing. GET /b2sc/jobs/{id}/result on the cohort answers 404 COHORT_CELLS_PER_BATCH; use the batch files, or GET /b2sc/jobs/{batch job_id}/result for one batch. GET /b2sc/jobs/{id} also lists the batches. In the SDK, download_cohort_cells(job_id) fetches them all (0.10.1).
Polling or streaming
GET /b2sc/jobs/{id} every 15 seconds is plenty and is what the SDK does. GET /b2sc/jobs/{id}/stream is server-sent events carrying the same fields every 3 seconds — it suits a browser, while for a script polling is simpler and survives a dropped connection without special handling.
How long it takes
Runtime varies with input size, model, resource availability and startup time. A client timeout does not cancel a job. Check the job identifier and continue polling its status before deciding whether to retry.
Python SDK
The supported way to drive Bulk to Single Cell from code — every tutorial above runs through it. It removes the two-step upload and the polling loop, and turns proportions into a DataFrame. Underneath it is plain HTTP: the HTTP reference at the end of this page documents every call, for integrations that do not use Python.
pip install 'wittgen-b2sc[pandas]' # drop [pandas] if you do not want DataFramesfrom wittgen_b2sc import B2SCClient, B2SCError, B2SCTimeout
client = B2SCClient(api_key="wgk_…") # or WITTGEN_API_KEY in the environmentMethod to endpoint
| Method | Calls | Notes |
|---|---|---|
| list_models() | GET /b2sc/models | Read applies_to and input_gene_contract before your first real submission. |
| list_atlases() | GET /b2sc/atlases | List the reference cohorts currently available to your account. |
| upload_file(path) | POST /b2sc/upload + PUT + GET /b2sc/input-files/status | All three steps, both required headers; returns the s3Key once the stored file is verified (wait=False returns it straight after the PUT). |
| wait_for_input(key) | GET /b2sc/input-files/status | Polls until the upload is verified; raises B2SCError with the code when it failed. |
| submit_job(model, source=…) | POST /b2sc/jobs | Accepts input_file_key or geo_accession; pass idempotency_key to make a retry safe. |
| get_job(job_id) | GET /b2sc/jobs/{id} | One poll. |
| list_jobs() | GET /b2sc/jobs | Follows the cursor for you and returns every job. |
| wait_for_completion(job_id) | GET /b2sc/jobs/{id} | Polls every 15 s; three-hour default timeout. A timeout does NOT cancel the job. |
| get_proportions(job_id, as_dataframe=True) | GET …/proportions | Returns a pandas DataFrame when asked. |
| get_results_data(job_id) | GET …/results-data | The summary and the run record: release, model, seed, cells per sample, the input contract. |
| list_files(job_id, category=…, include_raw=…) | GET …/files | The filter is applied server-side. |
| get_result(job_id) | GET …/result | The metered generated-matrix link. |
| get_usage() | GET /b2sc/usage | Your usage counts and daily budgets. |
DELETE /b2sc/jobs/{id} and GET /b2sc/models/{id}/required-genes have no wrapper in this SDK version — call them over HTTP if you need them (the upload tutorial shows the gene-list check).
Errors
B2SCError carries .code — the same code documented above — so you can branch on it. B2SCTimeout carries .elapsed and .last_status and does not mean the job stopped; keep polling get_job() or retry with a larger timeout.
try:
job = client.submit_job("t-all-2k-v2", source="geo", geo_accession="GSE000000")
except B2SCError as e:
if e.code == "GEO_SERIES_NOT_VERIFIED_FOR_MODEL":
print("verified for this model:", e.details.get("available", [])) # [] today
elif e.code == "GEO_AMBIGUOUS":
print("pick one:", [f["name"] for f in e.details["files"] if f["eligible"]])
else:
raiseErrors
Every refusal carries a machine-readable code alongside a message written for a person. Branch on code, show message. The retry column is the one that matters when nobody is watching: a code marked no will fail identically however many times you send it.
| Code | HTTP | What happened | What to do | Retry |
|---|---|---|---|---|
| API_KEY_INVALID | 401 | Missing, malformed or revoked key. | Check the header reads Authorization: Bearer wgk_…. A key is shown once at creation; if lost, revoke and mint another. | no |
| API_KEY_SCOPE_REQUIRED | 403 | The key is valid but was created without the permission scope this call needs. The body names it in required_scope (for example jobs:write). | Create a new key that includes that scope — scopes are fixed when a key is made. Keys created before scopes existed are not affected. | no |
| ACCOUNT_NOT_PROVISIONED | 403 | The account exists but has no active trial and is not enabled for Bulk to Single Cell. | Add an invitation code under Account, or contact us to have it enabled. | no |
| TRIAL_CREDIT_EXHAUSTED | 403 | The trial credit has been used up or has expired. Existing results stay readable. | Contact us to continue. | no |
| TRIAL_CREDIT_INSUFFICIENT | 402 | The submission is quoted (per batch of 64 samples) at more than the trial credit available for new work — the balance, less the reserve that is never held and credit held by running analyses. Refused before anything was created; nothing was charged. The body carries quote_micros, reservable_micros and samples_fit. A job the credit approval refuses after submit is CANCELLED with this code rather than left waiting. | Submit at most samples_fit samples, or wait for running analyses to finish. GET /b2sc/credit/quote checks before you upload. | no |
| TRIAL_BULK_BOUND_EXCEEDS_ALLOWANCE | 402 | The submission is quoted at more than the whole trial grant, so it can never run on this trial. Nothing was created or charged. | Submit fewer samples — samples_fit in the body is what fits now. | no |
| INVALID_SAMPLE_COUNT | 400 | GET /b2sc/credit/quote was called without a whole-number n_samples in range. | Pass n_samples from 1 to cohort.max_samples. | no |
| TRIAL_ACCESS_UNAVAILABLE | 503 | The trial credit grant behind this account could not be verified, so the request was not admitted. Nothing was started or charged. | Retry shortly. A trial account uses keys and the API exactly like a paid one; usage is debited from trial credit first. | yes |
| TERMS_ACCEPTANCE_REQUIRED | 403 | Terms have not been accepted on this account. | Sign in to the dashboard once and accept. | no |
| UNSUPPORTED_FILE_TYPE | 400 | fileName does not end in .tsv, .csv or .txt, optionally gzipped. | Rename the file to match its contents. The suffix is what is validated. | no |
| FILE_TOO_LARGE | 400 | Over 2 GB at the presign step. | Gzip the file — the limit applies to the bytes uploaded — or split the cohort into more than one submission. | no |
| INPUT_TOO_LARGE | 400 | The stored object is larger than declared, or than the limit. | Re-check the file you actually uploaded. | no |
| INPUT_TOO_LARGE_EXPANDED | 400 | The matrix decompresses past 4 GB (a cohort), or past 512 MB (one run of 64 samples or fewer — the model's own per-run ceiling). Read to the end at submit, before anything is queued. | Drop non-numeric annotation columns, or split the cohort into more than one submission. Do not remove gene rows: the model normalises over its full common gene set, so send the raw matrix as it is. | no |
| COHORT_TOO_MANY_SAMPLES | 400 | The header declares more sample columns than one submission may carry here: more than cohort.batch_size (64) where cohort splitting is off, or more than cohort.max_samples where it is on. GET /b2sc/models publishes all three. | Split the matrix column-wise into batches of 64 or fewer and submit one job per batch. The response names how many batches. Per-sample proportions concatenate directly, so the merged table is what one job would have produced. | no |
| COHORT_SAMPLE_COUNT_UNKNOWN | 400 | The first line could not be read as a header, so the number of samples is unknown. | The first line must be the header: one gene-identifier column, then one column per sample, tab- or comma-separated. Checked before the job is queued rather than assumed, because guessing here would run the wrong number of samples on a GPU and report a well-formed wrong answer. | no |
| INVALID_MODEL | 400 | disease_model is not one of the ids GET /b2sc/models publishes. | Use a current id: breast-tumour-2k-v2, t-all-2k-v2, sepsis-pbmc-2k-v1. An id from the previous generation is refused rather than redirected, because redirecting would answer with a different cell-type axis. | no |
| MODEL_NOT_PROVISIONED | 503 | The model exists but no engine revision is registered for its release in this environment yet. | Nothing on your side. The submission is refused rather than run on an unpinned engine; retry once the release is registered. | yes |
| GENE_IDS_MUST_BE_SYMBOLS | 400 | gene_id_type asked for identifier conversion on a model that matches its gene list verbatim. | Omit gene_id_type and re-label your gene column to the model's list (GET /b2sc/models/{id}/required-genes). Converting on the way in would hide the mismatch the list exists to show. | no |
| INVALID_IDEMPOTENCY_KEY | 400 | The key is malformed. | Printable ASCII, no spaces, at most 200 characters. | no |
| SUBMISSION_QUARANTINED | 500 | This submission failed repeatedly while it was being accepted and was stopped. Nothing was started or charged. | Check the input file, then submit again with a NEW Idempotency-Key. The error names the job id to quote to support. | no |
| IDEMPOTENT_REQUEST_IN_FLIGHT | 202 | This submission is still being accepted (a large matrix is checked in full first). job_id names the job the key reserved. | Wait Retry-After seconds and repeat the same request with the SAME key: it returns the job, or why it was refused. Do not submit again without it. | yes |
| IDEMPOTENT_JOB_GONE | 409 | The key was used for a job that no longer exists. | Use a new key. | no |
| GEO_AMBIGUOUS | 422 | The series has more than one file that looks like a gene-level count matrix and they score too closely to choose between. | The response carries the listing. Retry with geo_file naming the one you want — guessing would decide which matrix your results describe. | no |
| GEO_NO_RAW_COUNTS | 422 | The series publishes only transformed matrices. | Provide raw counts or declared quantifier expected counts with source provenance. Normalized or log-transformed input is incompatible. | no |
| INPUT_UNITS_NOT_COUNTS | 400 | You declared the matrix as already normalised (TPM, FPKM, CPM, log-normalised, VST). | Declared normalized units are incompatible with the model contract. Normalization cannot be reversed by the service. Submit raw counts or quantifier expected counts with appropriate provenance. | no |
| INPUT_DUPLICATE_GENE | 422 | The same gene identifier is on more than one row — any row, including one the model does not use. The model's own sentence, naming the row: "Gene symbols must be unique; duplicate found at row N." | Each identifier must appear once: one gene with two rows has no single value, and the gene contract allows no implicit sum, first or last choice. If a row was pasted or concatenated twice, remove the copy; if the rows are separate loci that share a symbol, decide yourself how to combine them before uploading. | no |
| INPUT_DUPLICATE_GENE_AFTER_MAPPING | 422 | Two DIFFERENT identifiers that the release's frozen dictionaries map to one gene — a versioned Ensembl id and its _PAR_Y twin, or a symbol and its Ensembl id. Both rows and both identifiers are named. | Renaming both would put one gene on two rows, which the gene contract refuses; we do not sum them for you. Resolve ambiguous identifiers using source annotation and a documented preprocessing decision. Preserve the original matrix; do not automatically drop or combine rows to force acceptance. | no |
| INPUT_NEGATIVE_VALUE | 422 | A value is negative. The model's own sentence names the row and the sample. | Negative values are incompatible with this input contract. Inspect source provenance and preprocessing; submit compatible count-scale source data. | no |
| INPUT_RAW_COUNT_REQUIRED | 422 | The model's parser classified the matrix as fixed_library_normalized: it has fractional values and every sample of a run (64 samples) totals 10,000 or 1,000,000, within rtol 1e-4 plus 1. | That is what CPM, TPM and counts per 10,000 do and raw counts do not. Submit the counts the values were computed from. An all-integer matrix is never refused this way. | no |
| INVALID_INPUT_UNITS | 400 | input_units is not one of the accepted values. | The response lists them. Omit the field if you are unsure — the matrix is classified from its values either way, and the declaration only settles the one band values cannot. | no |
| INVALID_ANALYSIS_MODE | 400 | analysis is not auto or manual. | Omit the field. No model in this release has an analysis stage, so the value changes nothing; it is validated for the day one does. | no |
| INVALID_GEO_ACCESSION | 422 | geo_accession is not a GEO series accession: GSE followed by digits only, such as GSE81538. Checked before the verified list. | Correct the accession. A sample (GSM) or platform (GPL) accession is not a series; use the GSE it belongs to. | no |
| GEO_SERIES_NOT_VERIFIED_FOR_MODEL | 422 | The accession is not one of the series we have run and checked against the current release. | Inspect the response for the current model-specific verification state. A separately uploaded matrix must still satisfy the sample, unit and required-gene contract. | no |
| GEO_SERIES_WRONG_MODEL | 422 | A verified series, but not for the model you asked for. | A series is verified against one model's gene list and tissue. Another model would return proportions for it that do not mean anything, so it is refused rather than answered. | no |
| GEO_NO_CANDIDATE | 422 | No gene-level count matrix found in the series. | The listing is returned so you can see what it actually contains. | no |
| ACCOUNT_NOT_FOUND | 403 | The authenticated account no longer exists. | Sign in again; contact support if the account should still be active. No job was created. | no |
| RATE_LIMITED | 429 | Two different ceilings answer with this code. SUBMISSIONS: more than 20 in a rolling hour, counted per account across every source. REQUESTS: more than 20 a minute on the metered read routes, counted per API KEY — so another key on the same account cannot spend yours. | Wait. Both windows roll, so they clear on their own. Do not retry in a loop. Read the Retry-After header rather than guessing which one you met. | yes |
| RAW_DOWNLOAD_BUDGET_EXCEEDED | 429 | Legacy refusal; no raw-download count cap is currently enforced. | GET /b2sc/usage reports counts; contact support if this legacy refusal appears. | yes |
| RESULT_ARCHIVED | 409 | The matrix has moved to archival storage. | Restore it yourself with POST /b2sc/jobs/{id}/restore (client.restore_job(job_id)); it is readable again in a few hours. Refused before anything is metered, because a presigned link to an archived object fails when followed. | no |
| JOB_DELETE_PENDING | 202 | Not an error: the delete is accepted and recorded, and a task of the run is still stopping. | Nothing to do. The data and the record are removed once the run has stopped; GET /b2sc/jobs/{id} shows deletion_pending until then. | no |
| JOB_WRITERS_NOT_STOPPED | 409 | A task of the run could not be stopped, or its state could not be read, so nothing was deleted. | Retry shortly; if it persists, contact us quoting the job id. | yes |
| PHI_CASCADE_INCOMPLETE | 409 | Some artifacts could not be erased, so the job record was deliberately kept rather than orphaning data. | Retry the delete; if it keeps failing, contact us quoting the job id. | yes |
Why a run was refused
The messages a FAILED job carries, quoted as they appear on the job — because the first thing anyone does with a failure message is search for it. The first three are the ones a first submission actually meets.
| The message you got | What it means | What to change |
|---|---|---|
| Historical run: Missing N common genes … | Your matrix lacks at least one identifier on the model's gene list. Almost always the gene column is spelled differently from the list — Ensembl ids where it has symbols, or symbols where it has Ensembl ids — or the matrix was filtered before export. | For a historical missing-gene refusal, check the policy version on that run. Current service preparation reports missing rows and assumes zero; preserve the original full available matrix and resolve identifier differences using verified source annotation. |
| Large missing-gene count after identifier preparation | A mismatch remains after supported identifier preparation. Review the reported identifiers against the required-gene list and source annotation. | Review supported identifier preparation and the reported duplicates. Resolve ambiguous mappings using source annotation and a documented preprocessing decision; preserve the original identifiers and annotation version. |
| … duplicate … Every gene identifier must appear once. … the model cannot choose between two rows for one gene. | Two rows carry the same identifier. This is the ordinary output of an Ensembl-to-symbol mapping, not a sign the file is broken. | Make each identifier appear once before upload. The platform does not sum or choose for you (the gene contract: no implicit sum, first or last), and refuses this at submit as INPUT_DUPLICATE_GENE, or INPUT_DUPLICATE_GENE_AFTER_MAPPING when two different identifiers map to one gene. |
| … finite and nonnegative … Raw counts are never negative, so this is normally a transformed matrix — log, z-scored or scaled — rather than one bad cell. | At least one value is negative or not a number. A count is never negative, so the matrix has been transformed. | Submit the counts this file was made from. Expected counts from salmon, kallisto or RSEM are fine; they are fractional but never below zero. |
| … positive common and panel library … At least one sample has no counts on the model's genes at all — an empty or wrong-tissue library. | A sample column sums to zero over the model's gene list. | Remove the sample, or check the matrix orientation: gene rows, sample columns. |
| The submitted matrix has N samples; one job takes at most 64. | Your matrix has more than 64 columns. Normally caught at submit (COHORT_TOO_MANY_SAMPLES); this is the engine's backstop. | Split into batches of 64 or fewer and submit one job per batch; the per-sample tables concatenate directly. |
| Gene symbols containing a path separator (for example the readthrough symbol THRA1/BTR) are refused. | A gene identifier contains a path separator. | Review the source annotation and preserve the original matrix before making a documented preprocessing decision. |
| Submit a .csv, .tsv, .csv.gz or .tsv.gz file. | Should not occur — the delimiter is detected from contents. | Contact support with the job id. |
| The pipeline ran out of memory and was stopped. This usually means the cohort is larger than the current configuration supports — contact us with the job id and we will re-run it with more. | The run outgrew the memory it was given. Nothing about your matrix is wrong. | Contact us with the job id. |
Limits and quotas
The submission API checks input before queueing when admission can complete, including required genes, row and sample limits and value constraints. The engine repeats validation. If preparation cannot complete at admission, the engine remains a validation backstop. Read the returned error code and input warnings.
| Limit | Value | Enforced | Notes |
|---|---|---|---|
| Samples per run | 64 | At submit, from the file’s own header | Where cohort splitting is enabled the matrix is ACCEPTED and split into runs of 64, spending one of your allowance per batch up to 4,096 samples in one submission; where it is not, it is refused at submit with a 400 (COHORT_TOO_MANY_SAMPLES) before anything is queued, so it costs nothing. GET /b2sc/models publishes which applies here, as cohort.enabled, cohort.batch_size and cohort.max_samples — read it rather than assuming a limit. |
| Input size | 2 GB as sent; 4 GB decompressed | At presign, and again at submit | Gzip accepted and recommended: the 2 GB applies to the bytes uploaded. Re-checked against the real object at submit, so a false fileSize fails there rather than later. The decompressed size is read to the end at submit, before anything is queued (INPUT_TOO_LARGE_EXPANDED). A matrix of more than 64 samples is split into runs of 64, and each run is held to the model's own 512 MB decompressed — a 64-sample slice of a gene-level matrix is tens of MB, so in practice only the whole-file limits bind. A one-hour upload window means a 2 GB file needs about 5 Mbit/s sustained. |
| Gene rows | 100,000 | At admission when input can be read; repeated in the engine | A gene-level human annotation is 40–60k and fits comfortably. A transcript-level matrix (~250,000 rows) does not — aggregate to gene level first. |
| Gene coverage | Missing rows reported and zero-padded | Dashboard preflight, submission admission and engine | Identifiers must be unambiguous and unique after supported preparation. Missing common and panel rows are reported and assumed zero by the service. NaN, infinity, negative values, and non-positive common or panel library sums are refused. A blank numeric CSV cell is interpreted as zero, not retained as an unknown value. |
| Submissions | 20 / hour | At submit | Per account, rolling, one budget across all three sources. Set well above what iterating on a file takes. |
| Raw .h5ad downloads | No download-count cap | At /result and /files?include_raw=1 | GET /b2sc/usage reports the rolling download count with cap_24h:null. Ownership and reference-dataset restrictions still apply. A reporting count does not authorize access or waive usage charges. |
| File size of a request body | n/a | — | Your matrix never passes through this API: it goes straight to S3 from your machine. |
| Retention | While your account is active | Automatic | Your uploads and results are kept while the account is active. When a trial ends or its credit is used up they stay downloadable for 7 days and are then deleted. Published atlases are permanent. |
Reproducibility and scope
Record the release_id and the model_id
Every model is served by an immutable release, and every job records the release and the model it ran against from the moment it is accepted. Results are comparable across jobs that share BOTH and not otherwise — when a model is replaced, the cell-type axis can change beneath the same product name. Keep them with your results; they are what lets you say months later what actually produced them.
Seeds and determinism
Every run uses the release's default seed, 20260904, which is fixed per release: there is no seed parameter on the API or in the UI. The release also ships weight sets for seeds 20260905 and 20260906, but they are not selectable yet. The engine records the seed, the device, the solver, the step count and every library version in run_manifest.json. The researcher reported exact reproduction of nine supplied cases on H100. This describes the tested cases and conditions; it does not establish biological validity or equality across GPU models.
Output checks and validation limits
| Guaranteed | Not claimed |
|---|---|
| Checkpoint, gene-list and cell-type-axis integrity, verified by hash before loading | Biological validity of the generated cells |
| The output contract, self-checked on every run (verification.json: shapes, finite non-negative expression, unique axes, allocation totals, output hashes) | Downstream biology, and formal differential expression |
| Reproducibility under the reported test conditions; no general hardware-independent guarantee | Equality across different GPU models |
| A clean, immutable distribution carrying its own release_id and model_id | |
| Input preparation records missing-gene zero-padding; invalid values, duplicates and empty common/panel libraries are refused |
Because downstream analysis is a separate evaluation, this inference release does not itself provide an automated downstream R analysis stage. The proportions and the generated cells are the complete result. validation_caveat on GET /b2sc/models states this per model, and it is the sentence to read before drawing a conclusion from a run.
Retention
While your account is active, the files you upload and the results you produce are kept. When your trial ends or its credit is used up, your files and results stay available to download for 7 days and are then deleted. You can delete an analysis and its files yourself at any time, or ask us through the contact form to delete your account and its data. DELETE /b2sc/jobs/{id} removes a job and its derived files. Deletion can remain pending while active work stops; poll until completion. Completed deletion is not reversible. Published atlases are permanent.
| What | How long | What you notice |
|---|---|---|
| The matrix you uploaded | while your account is active | You can re-run it by passing the same input_file_key. It is deleted with your other files 7 days after a trial ends or its credit is used up, or when you delete it. |
| Results and the generated matrices | while your account is active; archival storage after 90 days | Reads stay available throughout, but once an object has moved GET /b2sc/jobs/{id}/result, /proportions and /results-data answer 409 RESULT_ARCHIVED with the archive state (archived or restoring), rather than handing you a link that would fail or a bare error. Restore the job yourself with POST /b2sc/jobs/{id}/restore; it is readable again in a few hours. The file listing reports the state per file. |
| A GEO series we fetched for you | 30 days | Nothing — it is public data we cache, and the next job on that accession fetches it again. |
| Published atlases | permanent | Nothing. They are worked examples and are meant to stay quotable. |
License & terms
The Bulk to Single Cell API is offered as a closed beta. What a key does and does not allow is stated here in full view, because it shapes how you should evaluate: freely inside your organization, and through a conversation with us for everything beyond that.
- Outputs are Research Use Only — see the input contract and the scope section above.
- Do not share your key: activity under it is attributed to you.
- Feedback you provide about the beta may be used by WittGen to improve the service.
- A key used outside these terms may be revoked at any time.
The governing text is the WittGen Bulk to Single Cell API Terms.
Catalogue
From here down: every operation as plain HTTP, for integrations that do not use the Python SDK — R, a workflow engine, another language. Generating a client instead of writing one? Feed the OpenAPI specification — a JSON file for tools like openapi-generator or Postman, not for reading — into your generator. Nothing below adds capability; it is what the SDK calls underneath.
First: what you are allowed to run, and what each model demands of a file.
Every model, the tissue it applies to, its cell-type axis, its fixed common axis (as a count here and a list at required_genes_url), its platform_input_policy, the immutable release it runs on, its seeds and cells per sample, and the reference input published beside it. Read applies_to before you submit your own data, and validation_caveat before drawing a conclusion from a result.
RETURNS An object with a models array.
curl -H "Authorization: Bearer $WITTGEN_API_KEY" \
https://www.wittgenbio.com/api/v1/b2sc/models{
"models": [
{
"id": "breast-tumour-2k-v2",
"name": "Breast tumour",
"subtitle": "Breast tumour, bulk-conditioned single-cell generation (GSE176078 reference)",
"description": "Cell-type composition and 1,000 generated single cells per sample for bulk breast tumour RNA-seq",
"applies_to": "Human breast tumour tissue, bulk RNA-seq of the whole tumour including its microenvironment, raw counts.",
"not_applicable_to": "Blood, normal breast, other tumour types, cell lines or non-human samples.",
"validation_caveat": "Research model from the ICLR 2027 submission. Verified for output contract and fleet reproducibility; biological validity of generated cells is not claimed.",
"n_genes": 2000,
"n_cell_types": 11,
"cell_types": ["B-cells","Cancer Epithelial","Cycling T-cells","Endothelial","Fibroblast","Myeloid","NK","Normal Epithelial","PVL","Plasmablasts","T cells"],
"release_id": "iclr27-pbe-bcs-main-20261016",
"model_id": "iclr27-pbe-bcs-GSE176078",
"input_gene_contract": {
"kind": "exact_common_genes",
"required_genes": 16864,
"panel_genes": 2000,
"required_genes_url": "/api/v1/b2sc/models/breast-tumour-2k-v2/required-genes"
},
"seed_policy": { "default_seed": 20260904, "seeds": [20260904,20260905,20260906] },
"n_cells_per_sample": 1000,
"expression_semantics": "continuous BCS-corrected generated expression; not measured or integer counts",
"estimated_runtime_min": 1,
"reference_dataset": {
"filename": "GSE176078_bulk.csv",
"n_samples": 1,
"source": "GEO GSE176078, sample CID3586",
"description": "The release's golden case for this cohort: one breast tumour sample (CID3586) from GSE176078, the input the engine's own end-to-end check runs."
}
}
],
"analysis_stage_offered": false,
"cohort": { "enabled": false, "batch_size": 64, "max_samples": 64 }
}genes[] and n_required retain the full common axis for compatibility. panel_genes[] is the fixed 2,000-gene panel; platform_input_policy describes the service zero-padding policy. Use the full available raw matrix and inspect missing-gene warnings. The ETag includes the model manifest and policy version; send If-None-Match when refreshing the response.
| Parameter | In | Type | Notes |
|---|---|---|---|
| idrequired | path | string | A model id from GET /b2sc/models. An unknown id is 404. |
RETURNS Model and release identifiers, n_required, manifest_sha256, genes[], panel_genes[] and platform_input_policy.
curl -H "Authorization: Bearer $WITTGEN_API_KEY" \
https://www.wittgenbio.com/api/v1/b2sc/models/breast-tumour-2k-v2/required-genes{
"model": "breast-tumour-2k-v2",
"model_id": "iclr27-pbe-bcs-GSE176078",
"release_id": "iclr27-pbe-bcs-main-20261016",
"n_required": 16864,
"manifest_sha256": "f0e0ab7ad3f0b7f030e3de567dc021ae07290f479a7aea68710eb1e6db5334f8",
"genes": ["FAM87B", "LINC00115", "SAMD11", "NOC2L", "KLHL17", "…"],
"panel_genes": ["<fixed-panel-gene-1>", "…"],
"platform_input_policy": {
"version": "platform-zero-pad-v1",
"missing_genes": "zero_fill",
"panel_genes": 2000,
"common_genes": 16864
}
}Pre-computed public cohorts, so you can see real output at scale without waiting for a run of your own. Each is an ordinary job id: every read endpoint below accepts it. Atlases are read-only, owned by a system account, and permanent — the retention window does not apply to them. They are built per release; none is published for the current release yet, so the list is empty today.
RETURNS An object with an atlases array of job records — empty until the first atlas for this release is published.
curl -H "Authorization: Bearer $WITTGEN_API_KEY" \
https://www.wittgenbio.com/api/v1/b2sc/atlases{
"atlases": []
}Getting data in
Step one of three. Returns a URL to PUT your matrix straight to S3, and the s3Key to submit with. The object is uploaded directly. Follow the returned upload contract and the current service file-size limits.
| Parameter | In | Type | Notes |
|---|---|---|---|
| fileNamerequired | body | string | Must end in .tsv, .csv or .txt, optionally gzipped. The SUFFIX is what is validated, not the declared type. |
| fileSizerequired | body | integer | Bytes. Checked against the 2 GB ceiling (the file as sent) here, and against the real object at submit. |
| fileType | body | string | Content-Type the URL is signed with; defaults to text/plain. Whatever you declare, the PUT must repeat exactly. |
RETURNS uploadUrl (valid one hour), uploadHeaders and s3Key.
curl -sS -o upload.json -X POST https://www.wittgenbio.com/api/v1/b2sc/upload \
-H "Authorization: Bearer $WITTGEN_API_KEY" \
-H "Content-Type: application/json" \
-d '{"fileName":"my_cohort.tsv.gz","fileSize":10906492,"fileType":"application/gzip"}'
# then send every returned header:
jq -r '.uploadHeaders | to_entries[] | [.key, .value] | join(": ")' upload.json > upload-headers.txt
curl -X PUT -H @upload-headers.txt \
--data-binary @my_cohort.tsv.gz "<uploadUrl>"{
"uploadUrl": "https://<bucket>.s3.amazonaws.com/b2sc/uploads/…?X-Amz-Signature=…",
"uploadHeaders": {
"Content-Type": "application/gzip",
"x-amz-server-side-encryption": "aws:kms",
"x-amz-server-side-encryption-aws-kms-key-id": "<KMS key ARN returned by API>"
},
"s3Key": "<upload-key-returned-by-api>"
}Step two of three, after the PUT. The stored file is read end to end to verify it, which takes time proportional to its size, so it runs in the background: poll every few seconds until state is ready (submit the key) or failed (error says what to do). Repeating the call is safe (it only reads), a finished answer never changes, and a verification interrupted by a server restart can read stalled: true. Continue polling and inspect the returned state; recovery time is not guaranteed.
| Parameter | In | Type | Notes |
|---|---|---|---|
| keyrequired | query | string | The s3Key from POST /b2sc/upload. Any key that is not your upload is 404. |
RETURNS state (incomplete | validating | ready | failed), ready, verified_bytes, total_bytes; code and error when failed or incomplete.
curl -sS -G https://www.wittgenbio.com/api/v1/b2sc/input-files/status \
--data-urlencode "key=<upload-key-returned-by-api>" \
-H "Authorization: Bearer $WITTGEN_API_KEY"{
"s3Key": "<upload-key-returned-by-api>",
"state": "validating",
"ready": false,
"verified_bytes": 4194304,
"total_bytes": 10906492
}Running a job
Starts a run and returns immediately with a job id. Three sources: the reference input published beside the model, a matrix you uploaded, or a public GEO accession. Send an Idempotency-Key to make a retry safe. The job records the release and model it will run under from the moment it exists. The whole matrix is checked before a job is accepted, so a large cohort can take a minute or more. Send Prefer: respond-async to be answered at once for a matrix over 8 MiB; without it the call waits up to about 20 seconds. A submission still being accepted is answered 202 IDEMPOTENT_REQUEST_IN_FLIGHT with the job_id it reserved and Retry-After, and the acceptance continues on the server. Repeat the same request with the same key until it returns the job (200) or the reason it was refused. A request without a key is given one in that 202 (idempotency_key).
| Parameter | In | Type | Notes |
|---|---|---|---|
| disease_modelrequired | body | string | An id from GET /b2sc/models: breast-tumour-2k-v2, t-all-2k-v2, sepsis-pbmc-2k-v1. Any other value — including the ids of the previous generation — is refused with 400 INVALID_MODEL rather than redirected, because redirecting would answer with a different cell-type axis. |
| sourcerequired | body | enum | reference_dataset | user_upload | geo |
| input_file_key | body | string | The s3Key from POST /b2sc/upload. Required when source=user_upload. Reusable: submit the same key to two models whose gene lists it satisfies. |
| geo_accession | body | string | Required when source=geo. Only accessions verified against the current release are accepted; none is yet — see the GEO tutorial. |
| geo_file | body | string | Name a specific supplementary file. Use this after a GEO_AMBIGUOUS refusal. |
| input_units | body | enum | raw_counts | expected_counts | tpm | fpkm | rpkm | cpm | normalized | log_normalized | vst. Declare units from source provenance. Normalized units are refused; declaring units does not convert the matrix. Numeric checks alone cannot establish the correct units. |
| gene_id_type | body | enum | Omit it. These models match the gene column VERBATIM against their own list (after the release-bound preparation of an uncompressed upload), so the only accepted value is the default (symbols as the list spells them); asking for Ensembl conversion is refused with 400 GENE_IDS_MUST_BE_SYMBOLS, because renaming identifiers on the way in would hide the mismatch the required-genes check exists to show. Re-label the file to the list instead. |
| Idempotency-Key | header | string | Printable ASCII, no spaces, ≤200 characters. Replaying it returns the same job. Lifetime 24 hours. |
RETURNS The accepted job: id, status, the release and model it will run under, and an estimate. A submission over 64 samples also returns n_samples and batch_count.
curl -X POST https://www.wittgenbio.com/api/v1/b2sc/jobs \
-H "Authorization: Bearer $WITTGEN_API_KEY" \
-H "Content-Type: application/json" \
-d '{"disease_model":"breast-tumour-2k-v2","source":"reference_dataset"}'{
"job_id": "bb468d69-3f2a-4c81-9e77-1a2b3c4d5e6f",
"status": "QUEUED",
"disease_model": "breast-tumour-2k-v2",
"release_id": "iclr27-pbe-bcs-main-20261016",
"model_id": "iclr27-pbe-bcs-GSE176078",
"estimated_runtime_min": 1,
"created_at": "2026-10-17T13:26:29.000Z"
}The call you poll. Stop on COMPLETED or FAILED; on FAILED, message says what to change. A finished job also carries what the run recorded about itself: the seed it used, the cells it generated per sample, and the cell-type axis.
| Parameter | In | Type | Notes |
|---|---|---|---|
| idrequired | path | string | Job or atlas id. |
RETURNS The job record.
curl -H "Authorization: Bearer $WITTGEN_API_KEY" \
https://www.wittgenbio.com/api/v1/b2sc/jobs/{id}{
"job_id": "bb468d69-3f2a-4c81-9e77-1a2b3c4d5e6f",
"status": "COMPLETED",
"disease_model": "breast-tumour-2k-v2",
"release_id": "iclr27-pbe-bcs-main-20261016",
"model_id": "iclr27-pbe-bcs-GSE176078",
"seed": 20260904,
"n_cells_per_sample": 1000,
"n_samples": 1,
"n_cell_types": 11,
"cell_types": ["B-cells","Cancer Epithelial","Cycling T-cells","Endothelial","Fibroblast","Myeloid","NK","Normal Epithelial","PVL","Plasmablasts","T cells"],
"progress": 100,
"message": "Inference complete (7 files)",
"estimated_runtime_min": 1,
"created_at": "2026-10-17T13:26:29.000Z"
}Newest first, cursor paginated. Follow cursor until it is null. The cursor is opaque and tied to the key it was issued to — pass it back unchanged, and do not try to read it.
| Parameter | In | Type | Notes |
|---|---|---|---|
| limit | query | integer | Page size. |
| cursor | query | string | The cursor from the previous page, verbatim. |
RETURNS jobs[] plus cursor when more remain, null on the last page.
curl -H "Authorization: Bearer $WITTGEN_API_KEY" \
"https://www.wittgenbio.com/api/v1/b2sc/jobs?limit=25"{
"jobs": [ { "job_id": "…", "status": "COMPLETED", "…": "…" } ],
"count": 25,
"cursor": "9tK1s…"
}Server-sent events carrying the same fields as the job record, every 3 seconds. Suits a browser; for a script, polling is simpler and survives a dropped connection.
| Parameter | In | Type | Notes |
|---|---|---|---|
| idrequired | path | string | Job id. |
RETURNS text/event-stream.
curl -N -H "Authorization: Bearer $WITTGEN_API_KEY" \
https://www.wittgenbio.com/api/v1/b2sc/jobs/{id}/streamevent: status
data: {"status":"RUNNING_STAGE1","progress":25,"message":"Stage 1: predicting cell-type proportions"}
event: done
data: {"status":"COMPLETED","runtime_seconds":31}Removes the record and cascades to every stored object — the input you submitted, the result files and the generated cells. Not reversible, and logged. Your own jobs only; an atlas belongs to a system account and is refused. A job that is still running is stopped first. If it has not stopped within a few seconds the answer is 202 JOB_DELETE_PENDING: the deletion is recorded and finished for you once the run has stopped, normally within a minute. Until then GET /b2sc/jobs/{id} shows deletion_pending: true, and afterwards it answers 404. Repeating the DELETE is safe.
| Parameter | In | Type | Notes |
|---|---|---|---|
| idrequired | path | string | Job id. |
RETURNS Confirmation of what was removed.
curl -X DELETE -H "Authorization: Bearer $WITTGEN_API_KEY" \
https://www.wittgenbio.com/api/v1/b2sc/jobs/{id}{ "deleted": true, "job_id": "…" }Withdraws a job that has not started on a GPU — PENDING, AWAITING_CREDIT, QUEUED or SPLITTING; for a large cohort, the whole analysis and every batch. The job becomes CANCELLED, can no longer start, and nothing is charged for it. Safe to repeat: a cancelled job answers the same way again. A job already running cannot be cancelled — delete it to stop it. After a cancel, DELETE removes the record and its data as usual. If another operation on the job may still be writing, the answer is 409 JOB_OPERATION_BUSY and nothing changes: retry in a few minutes.
| Parameter | In | Type | Notes |
|---|---|---|---|
| idrequired | path | string | Job id (for a cohort, the parent id). |
RETURNS The job id and its new status.
curl -X POST -H "Authorization: Bearer $WITTGEN_API_KEY" \
https://www.wittgenbio.com/api/v1/b2sc/jobs/{id}/cancel{ "job_id": "…", "status": "CANCELLED", "already_cancelled": false, "batches_cancelled": 0, "charge_voided": true }Taking results out
Read per-sample proportions, the results summary or the file list. Raw download links are issued through /result or /files?include_raw=1. These raw-download paths are metered; a summary read is a separate operation. Read expires_in for the lifetime of each issued link.
Per-sample cell-type proportions. Long format has one row per sample and cell type; wide format has one row per sample. Values sum to 1 within rounding. Interpret only inputs compatible with the model contract; declare source units at submission.
| Parameter | In | Type | Notes |
|---|---|---|---|
| idrequired | path | string | Job or atlas id. |
| format | query | enum | long (default) or wide. |
RETURNS cell_types in their fixed order, the proportions themselves, and a presigned CSV.
curl -H "Authorization: Bearer $WITTGEN_API_KEY" \
"https://www.wittgenbio.com/api/v1/b2sc/jobs/{id}/proportions?format=long"{
"job_id": "bb468d69-3f2a-4c81-9e77-1a2b3c4d5e6f",
"disease_model": "breast-tumour-2k-v2",
"n_samples": 1,
"cell_types": ["B-cells","Cancer Epithelial","Cycling T-cells","Endothelial","Fibroblast","Myeloid","NK","Normal Epithelial","PVL","Plasmablasts","T cells"],
"format": "long",
"proportions": [
{ "sample": "CID3586", "cell_type": "B-cells", "proportion": 0.028853 },
{ "sample": "CID3586", "cell_type": "Cancer Epithelial", "proportion": 0.224694 },
{ "sample": "CID3586", "cell_type": "Fibroblast", "proportion": 0.332837 }
],
"downloads": { "proportions_csv": "https://… (presigned, 15 min)" },
"intended_use": "Research Use Only. Not a medical device. …"
}Mean proportions across the cohort plus the run record — the release and model, sample count, the cell-type axis, the seed, cells per sample, what the generated values ARE, the engine code version, and the input contract the run was held to. The at-a-glance view; use /proportions for per-sample numbers.
| Parameter | In | Type | Notes |
|---|---|---|---|
| idrequired | path | string | Job or atlas id. |
RETURNS metadata, mean proportions, and the Research Use Only notice.
curl -H "Authorization: Bearer $WITTGEN_API_KEY" \
https://www.wittgenbio.com/api/v1/b2sc/jobs/{id}/results-data{
"job_id": "bb468d69-3f2a-4c81-9e77-1a2b3c4d5e6f",
"metadata": {
"disease_model": "breast-tumour-2k-v2",
"model_id": "iclr27-pbe-bcs-GSE176078",
"release_id": "iclr27-pbe-bcs-main-20261016",
"n_samples": 1,
"n_cell_types": 11,
"cell_types": ["B-cells","Cancer Epithelial","Cycling T-cells","Endothelial","Fibroblast","Myeloid","NK","Normal Epithelial","PVL","Plasmablasts","T cells"],
"n_genes": 2000,
"n_cells_per_sample": 1000,
"seed": 20260904,
"expression_semantics": "continuous BCS-corrected generated expression; not measured or integer counts",
"engine_code_version": "<engine-code-version>",
"runtime_seconds": 31,
"created_at": "2026-10-17T13:26:29.000Z",
"input_contract": { "kind": "exact_common_genes", "required_genes": 16864, "satisfied": true }
},
"proportions": [
{ "name": "Fibroblast", "mean": 0.332837 },
{ "name": "Cancer Epithelial", "mean": 0.224694 }
],
"intended_use": "Research Use Only. Not a medical device. …"
}One entry per artifact with a presigned URL valid for an hour. The primary way to collect a finished run. Listing is free and you may call it as often as you like — links expire, so re-list rather than storing them. Every result file sits directly under the job's result prefix, and platform_manifest.json names each of them.
| Parameter | In | Type | Notes |
|---|---|---|---|
| idrequired | path | string | Job or atlas id. |
| category | query | string | Filter to one kind: result · input. |
| include_raw | query | boolean | Presign the generated matrices here (.h5ad and .npz). OFF by default, because presigning them spends one of your rolling 24-hour raw downloads and listing your files should not cost a download. Without it they are listed with an empty url and reason RAW_NOT_REQUESTED. |
RETURNS files[] — name, type, category, size, and url.
curl -H "Authorization: Bearer $WITTGEN_API_KEY" \
https://www.wittgenbio.com/api/v1/b2sc/jobs/{id}/files{
"files": [
{ "name": "proportions.csv", "type": "csv", "category": "result",
"size": 212, "url": "https://… (presigned, 1 h)" },
{ "name": "cell_counts.csv", "type": "csv", "category": "result",
"size": 164, "url": "https://…" },
{ "name": "platform_manifest.json", "type": "text", "category": "result",
"size": 1180, "url": "https://…" },
{ "name": "run_manifest.json", "type": "text", "category": "result",
"size": 4312, "url": "https://…" },
{ "name": "verification.json", "type": "text", "category": "result",
"size": 640, "url": "https://…" },
{ "name": "generated_cells.h5ad", "type": "h5ad", "category": "result",
"size": 8402944, "url": "", "restricted": true, "reason": "RAW_NOT_REQUESTED" }
]
}| File | What it is |
|---|---|
| platform_manifest.json | The index of the result: release_id, model_id, seed, n_cells_per_sample, n_samples, the cell-type axis, the engine code version and image digest, the input sha256, expression_semantics, and the name of every other file. |
| proportions.csv | One row per sample (sample_id), one column per cell type, six decimal places. Each row sums to 1 within that rounding. |
| cell_counts.csv | The same table as integer cell counts — how many of the generated cells per sample were allocated to each type. |
| generated_cells.h5ad | The generated cells as AnnData: obs carries sample_id and cell_type; var is the 2,000-gene panel; X is continuous BCS-corrected generated expression; not measured or integer counts. |
| generated_cells.npz | The same matrix and axes as compressed NumPy arrays, for readers without an AnnData stack. |
| run_manifest.json | The engine's own record of the run: solver, steps, batch size, seed, device and library versions, and the sha256 of every checkpoint it loaded. |
| verification.json | The engine's self-check of the output contract — shapes, finite non-negative expression, unique axes, allocation totals, checkpoint load, output hashes. PASS or the job does not complete. |
| restricted reason | What it means | What to do |
|---|---|---|
| RAW_NOT_REQUESTED | The generated matrix exists but you did not ask for it. | Re-list with ?include_raw=1. |
| REFERENCE_DATASET | The job ran on a reference dataset we ship — including the one the Quickstart tells you to run. The proportions are yours; the generated matrix is not. | Run the same model on a matrix of your own. |
| RAW_OUTPUT_OWNER_ONLY | The job is readable by you but not yours — a published atlas. | Run your own cohort. |
| INPUT_OWNER_ONLY | The input file belongs to whoever uploaded it. | Nothing — you already hold your own input. |
| RAW_DOWNLOAD_BUDGET_EXCEEDED | Legacy raw-download cap refusal; no download-count cap is currently enforced. | Check GET /b2sc/usage for reporting counters; contact support if this legacy refusal appears. |
A presigned link to the .h5ad itself, signed for 15 minutes. Downloads are counted for reporting without a download-count cap. Fetch it immediately rather than storing or forwarding the link. The matrix carries 1,000 generated cells per sample over the model's 2,000-gene panel — the release's setting, not configurable per request — and its values are continuous BCS-corrected generated expression; not measured or integer counts. Do not feed it to a tool that expects integer counts.
| Parameter | In | Type | Notes |
|---|---|---|---|
| idrequired | path | string | Job id. Atlases are deliberately excluded. |
RETURNS downloadUrl, an optional contextUrl, the link lifetime, and the stable S3 key.
curl -H "Authorization: Bearer $WITTGEN_API_KEY" \
https://www.wittgenbio.com/api/v1/b2sc/jobs/{id}/result{
"downloadUrl": "https://… (presigned, 15 min)",
"contextUrl": null,
"expires_in": 900,
"result_s3_key": "b2sc/results/<user>/<job>/generated_cells.h5ad",
"runtime_seconds": 31
}Account
What you are allowed and what has been consumed: plan, job quota, a 30-day per-operation ledger, and raw-download reporting counters without a count cap. Read your own figures here rather than planning against the numbers on this page. Two scopes are mixed and it matters which is which: **metered_30d is YOUR KEY’s** activity, while **plan, used, quota and raw_downloads are the ACCOUNT’s** — and an account can carry more than one key. If your metered_30d looks smaller than `used`, that is why, not a lost job.
RETURNS plan, quota, metered_30d and raw_downloads.
curl -H "Authorization: Bearer $WITTGEN_API_KEY" \
https://www.wittgenbio.com/api/v1/b2sc/usage{
"plan": "paid",
"used": 15,
"quota": null,
"remaining": null,
"enforced": true,
"metered_30d": [
{ "op": "gpu_job", "unit": "op", "events": 15, "total": 15 },
{ "op": "raw_download", "unit": "op", "events": 2, "total": 2 }
],
"raw_downloads": { "used_24h": 2, "cap_24h": null }
}On a trial, a submission is charged per successful batch of 64 samples, and it is checked against your credit BEFORE anything is created: POST /b2sc/jobs refuses one that cannot fit with 402 TRIAL_CREDIT_INSUFFICIENT (more than the credit available for new work) or TRIAL_BULK_BOUND_EXCEEDS_ALLOWANCE (more than the whole grant). This asks the same question before you upload. The answer names the quote, what is available, and samples_fit — the largest submission that fits now. It is advisory: the submission is checked again. credit_funded false means your runs are not charged against a trial wallet.
| Parameter | In | Type | Notes |
|---|---|---|---|
| n_samplesrequired | query | integer | Sample columns in the matrix you intend to submit. |
RETURNS credit_funded, fits, the quote and balance in micros (millionths of a dollar), batches_fit and samples_fit; error and code when it does not fit.
curl -H "Authorization: Bearer $WITTGEN_API_KEY" \
"https://www.wittgenbio.com/api/v1/b2sc/credit/quote?n_samples=3264"{
"credit_funded": true,
"fits": false,
"currency": "USD",
"n_samples": 3264,
"batch_size": 64,
"batches_required": 51,
"unit_price_micros": "2000000",
"quote_micros": "102000000",
"granted_micros": "100000000",
"available_micros": "85440000",
"floor_micros": "1000000",
"reservable_micros": "84439999",
"batches_fit": 42,
"samples_fit": 2688,
"code": "TRIAL_BULK_BOUND_EXCEEDS_ALLOWANCE",
"error": "This submission cannot run on a trial: …"
}