Helical Platform

Returns runs, newest first, with their current state. There is no project or owner parameter — you see your own runs and only those. Optional filters (`dagIds`, `state`, `baseModel`, `tags`, date range, …) narrow the list; multi-value ones are comma-separated. `limit` caps how many of the most-recent runs come back (default 50), and `total_entries` is how many matched in all. Each row's `child_runs` lists the downstream runs that consumed that run's output (lineage). Use this to see recent or in-flight jobs; to poll a single run, or to reach its artifacts, `getRunDetails` is cheaper. Spends no credit.

Returns the single-cell (`DataScMeta`) dataset catalog the user can run analyses against. Sequence-RNA datasets are not returned here. Use this when the user asks 'what datasets do I have?' or to find a dataset's UUID before passing it to other tools. Pass the returned `id` as `datasetId` to the tools that take a dataset (they translate it to the on-disk path server-side). Only datasets in your projects are listed. Spends no credit. Optional filters (`name`, `author`, `organism`, `tissue`, `disease`, `dataPath`) AND together in a single call — each filter narrows the result set, no need to issue multiple calls. String fields (`name`, `author`, `dataPath`) match on a case-insensitive substring; array fields (`organism`, `tissue`, `disease`) match if the dataset's array contains the value exactly.

Returns both kinds of model this listing covers. `base_models` is the foundation-model catalog — available immediately, no fine-tuning required. `models` is this workspace's registry of fine-tuned models, newest-promoted first. This is the single model-discovery surface. For a `base_models` entry, pass its `name` verbatim as a trigger tool's `model` and omit `model_version`. For a `models` entry, pass its `name` plus its `version` as `model_version` — NOT its `base_model`, which names the foundation it descends from. `status` applies to `models` only: a foundation model is neither promoted nor a promotion candidate, so it is never filtered by it. Defaults to `all`: every fine-tuned model in this workspace can launch, promoted or not. Every entry carries `credits_per_cell` and `credits_per_job`, so a run can be quoted before it is triggered: credits_per_job + cells × passes × credits_per_cell, where passes is 1 for an embedding and 6 × epochs for fine-tuning. A validation dataset adds its own cells × 1 × epochs. A fine-tuned model is charged at the rate of the foundation model it descends from, which is why its price follows its `base_model`. This listing covers single-cell models only.

Lists the actions queued under your project that are still waiting for a decision, newest first. Each entry carries the `confirmation_id` needed to poll it with `getConfirmationStatus` or settle it with `resolveConfirmation`, and, for a queued launch, a `summary` of what that run will do; for queued feedback, a `summary` holding the exact message. Any other action has `summary: null` and is named by `target_label` CALL THIS BEFORE RE-REQUESTING A QUEUED ACTION. A queuing tool that returns 409 (`A pending approval for this operation already exists.`) does not hand back the id, and this is the only way to recover it — re-requesting the action instead of listing will just 409 again. Only `pending` actions appear. One that was approved, rejected or expired drops out of this list; read its outcome with `getConfirmationStatus`. Past-due entries are already excluded, so the list is never stale.

Queues a feedback message to the Helical team. Use it when the user asks to report something or send feedback. When you hit an obstacle — a tool error, a failed run, a missing capability, a blocked action — you may offer to raise feedback, once for that obstacle; do not offer again for it. ASK FIRST. Draft the message, show the user the exact text, and call this only after they agree to send it. Never call it on your own initiative. Include what was attempted, the failing tool or run id, and the error. The user, instance and this conversation or project are added for you. Nothing is sent by this call: it returns `status: 'pending_approval'` + a `confirmation_id`, and the feedback is sent only once approved. Show the user the exact message and approve it with `resolveConfirmation` only once they agree; on a 409, recover the pending one's id with `listPendingConfirmations`. 409 means a feedback message is already waiting for approval here; only one can be pending at a time. If the approved feedback ends `failed`, tell the user it was not delivered — for example, feedback is not configured on this instance.

Step 3 of 3: creates the catalogue row for an object already uploaded via `initiateDatasetUpload` + `completeDatasetUpload`, making the dataset visible in the dashboard's Data tab and usable by the trigger tools. Pass the `s3Key` that `completeDatasetUpload` returned. Side effects: copies the uploaded file to the project's canonical dataset path and writes the catalogue row plus the project's access grant. 409 if the project already has a dataset with this `name`.

Resolves a `confirmation_id` returned by a tool that queued an action instead of running it. `approve` executes the queued operation inline and returns once it has run, reporting what it did in `outcome`; `reject` discards it. This is the only place that `outcome` is returned ASK THE USER FIRST. When the queued action is a run, quote its cost: approving spends their credit. When it is feedback, show them the exact message from its `summary`: approving sends it. Otherwise name what it changes (`target_label`). Approval cannot be reversed from here — this call IS their approval, so never make it on your own initiative or to retry something they declined. Each confirmation resolves once. A second call on the same id — and one on an id that has already expired — 404s. Read the outcome later with `getConfirmationStatus`. A 402 means the user's balance could not cover the run, and a 400 saying the quote can no longer be spent means it is no longer usable — in both cases nothing was launched, the confirmation is spent, and the run must be re-requested from the tool that created it. 500 means it was approved but failed to run; it also stays resolved and must be re-queued. For a dataset action, 403, 404 or 409 on an id that was still pending means approval found the request no longer valid (write access lost, dataset deleted or no longer in the project, name taken): nothing changed, the confirmation is spent, and it must be re-requested. Check `getConfirmationStatus` first — `failed` means nothing changed; `executed` means an earlier call already ran it.

Queues an embedding run that produces embeddings for a single-cell dataset using a foundation (or fine-tuned) model. Use when the user asks to embed / extract representations / compute features from a dataset. Does NOT launch directly. ASK THE USER BEFORE APPROVING: the run consumes GPU compute in their account, and where billing is enabled it spends their credit. The run is queued for your own approval and starts only once you approve it. Returns `status: 'pending_approval'` + a `confirmation_id`; approve or reject it with `resolveConfirmation`, and read its outcome with `getConfirmationStatus`. Sequence models are refused: this tool embeds the single-cell datasets `listDatasets` returns.

Queues a fine-tuning run. One model per call. Use this when the user asks to fine-tune a model — for example: 'fine-tune scGPT on the lung dataset with label LVL3'. `labels`, `task_type`, and `model_type` are parallel arrays — one entry per task. Commonly-successful values (from prior successful runs; guidance, not hard limits): `learning_rate` 1e-4, `num_trainable_layers` 1–2, `batch_size` 16, `weight_decay` 0.01, `lr_scheduler` 'constant', `seed` 42; start with `epochs` 1 and increase only if under-fit. The price counts 6 passes per epoch over each training cell, plus 1 per epoch over each cell of the `valDatasetId` dataset if one is given, at the model's per-cell rate from `listModels`. So a fine-tune costs many times an embedding of the same dataset, and `epochs` is the term to reason about. A hyperparameter search is not offered here: one run trains one configuration. Validation runs once an epoch over the dataset `valDatasetId` names, and the quote counts its cells; datasets arrive pre-split, so `val_split` is not offered, nor is a per-step validation cadence. Does NOT launch directly. ASK THE USER BEFORE APPROVING: the run consumes GPU compute in their account, and where billing is enabled it spends their credit. The run is queued for your own approval and starts only once you approve it. Returns `status: 'pending_approval'` + a `confirmation_id`; approve or reject it with `resolveConfirmation`, and read its outcome with `getConfirmationStatus`.

Queues a perturbation run that predicts, with PerturbGen's decoder, how masking a gene changes a labeled .h5ad dataset's cells at later time points. Use when the user asks what masking a gene would do to cells at later time points — for example: 'mask IL1B in the 90-minute LPS cells and predict them at 6 h and 10 h'. Generation is `estimator: 'perturbgen'`, the one estimator this tool offers. Each gene in `target_genes` is masked in every source cell that holds it, and the decoder predicts each cell at every time point in `perturbgen_config.pred_tps`. The edit is fixed to a mask, so there are no regulation factors to choose. Cells: `group_obs_key` and `groups_to_perturb` pick the source cells, and `n_cells_perturbed` (at most 2000) samples them. The quote charges two runs per gene for every source cell, unedited and masked, and one more run per source cell for the gene embeddings. The unedited run is the control. The model shares one unedited run per cell across the genes and decodes only the cells holding each gene, so the quote carries a margin over the work done. Each run is one encoder pass plus one decoder pass per time point in `perturbgen_config.pred_tps` (default 1, 2), and the quote charges each decoder pass as 15 passes. `perturbgen_config.n_samples` count draws, at most 100, are averaged per predicted cell; the quote does not charge for them. Genes: only genes in the decoder's 1,856-gene LPS vocabulary can be masked. A gene outside the vocabulary or the dataset counts as missing and is dropped, and the run fails when more than 20% of `target_genes` are missing. A symbol and its Ensembl id name one gene, so listing both fails the run. The quote counts every listed gene. One run per call; for several gene lists, make N calls. Follow the run with `listDagRuns` / `getRunDetails`; once it succeeds, `getRunDetails` lists what it produced and `downloadArtifact` fetches any of those files. Does NOT launch directly. ASK THE USER BEFORE APPROVING: the run consumes GPU compute in their account, and where billing is enabled it spends their credit. The run is queued for your own approval and starts only once you approve it. Returns `status: 'pending_approval'` + a `confirmation_id`; approve or reject it with `resolveConfirmation`, and read its outcome with `getConfirmationStatus`.

Queues an edit to a dataset's name or descriptive metadata. Nothing changes until `resolveConfirmation` approves the returned `confirmation_id`. Spends no credit. Send only the fields to change. A list field replaces the stored list rather than adding to it, and null clears `donorCount`, `link`, `linkPublication`, `linkData` or `licence`. Measured counts, the file location, status and `.obs` column names cannot be edited here. 400 if the body is empty or names a field this tool does not accept. 404 if the dataset doesn't exist or is deleted. 403 if the user has read-only access. 409 if the new name is taken, or an edit of this dataset is already queued — recover its `confirmation_id` with `listPendingConfirmations`.

Answers 'who am I signed in as', and 'how much credit do I have left' `credits_balance` moves as runs are charged, so read it again rather than reusing an earlier figure. `console` is where a human goes to act on any of this.