For researchers

Preparing Boltz batches

Prepare multiple plans from single protein sequences in CSV/FASTA, and check inputs, setting combinations, and submission eligibility.

To predict multiple protein sequences under the same conditions or compare settings, open Execution plans → Create multiple plans from a table in your project. Creating plans does not start GPU computation. Boltz appears in the selector only when a runnable version is published to your organization.

Supported inputs

Batch input currently accepts one protein chain per CSV data row or FASTA entry. A chain is one continuous protein sequence; this path stores it as chain A. It does not accept chains joined with :, nucleic acids, ligands (small molecules that bind to proteins), or per-row MSA files. Use individual complex input for multiple components.

You must acknowledge Predict from a single sequence without MSA. An MSA aligns related protein sequences as reference information. Omitting it may reduce prediction quality. Selecting single-sequence mode does not validate that quality.

Here is a CSV example. Column headers and job names may use Korean. Keep the original one-letter amino acid codes in the sequence.

name,sequence
First candidate,ACDEFGHIKLMNPQRSTVWY
Second candidate,MQIFVKTLTGKTITLEVEPSDTIENVKAKIQDKEGIPPDQQRLIFAGKQLEDGRTLSDYNIQKESTLHLVLRLRGG

This illustrates input format, not recommended candidates or guaranteed prediction quality. For FASTA, prepare each > header and its following sequence as one entry.

From file to plan

  1. Select Boltz version
  2. Select or upload file
  3. Map columns
  4. Preview
  5. Create plans
  1. Select the Boltz tool and version, then acknowledge the single-sequence conditions.
  2. Choose an inspected stored file, or upload CSV/FASTA with Upload a file here. Upload completion is separate from input inspection. Select the file after it appears as inspected. The list refreshes automatically until inspection finishes. If it takes too long or the list fails to load, select Refresh file list.
  3. Use the actual column names shown to select the Protein sequence column. The Job name column is separate from computational input; select the column containing names.
  4. Choose setting combinations and select Preview. Review Data rows, Plans that can be created, Inputs/settings to fix, and Blank rows to skip separately.
  5. Fix errors and select Create plans. Review saved plans, current submission conditions, terms, and usage before submitting. If every plan has a job name from the file, no additional name is needed. A fallback name is requested only for unnamed plans; row numbers are appended only to those names.

Setting combinations

You can combine seed (random seed), numSamples (structures to generate), numRecycles (structure recycling steps), and stepScale (sampling step scale). Do not assign one setting both to a file column and a sweep axis.

For example, applying seeds 7 and 11 to two valid sequence rows creates four plans. numSamples=2 generates two structures within one plan; it does not create two data rows. Use the preview and creation receipt for final counts after errors and blank rows are accounted for. More recycling steps or samples do not guarantee higher accuracy.

Preparing through an AI tool

MCP and the CLI use the same batch-plan service. Get the current release and manifestHash with list_execution_options, and preserve the source SHA, generation, and inspectionVersion from inspect_input. Call preview_batch_plans with mappings: [] to read actual headers, then map columns and preview again.

If the first column is the name and the second is the sequence, as above, use the following settings. This example shows only mappings, shared settings, and the sweep, not a complete request.

{
  "toolType": "boltz",
  "mappings": [{"settingName": "sequence", "columnIndex": 1}],
  "nameColumn": 0,
  "baseSettings": {"proteinMsaMode": "single-sequence", "numSamples": 1, "numRecycles": 1},
  "sweep": {"mode": "cross", "axes": [{"settingName": "seed", "kind": "list", "values": ["7", "11"]}]}
}

Column indexes start at 0. A real request also needs the project, source file, inspection details, release, and manifestHash. Creation additionally requires batchRequestId. Read approval.status and reason in the creation response.

For Boltz plans created with a Nadoo Bio API key, open the returned batch approval link, review inputs, settings, and terms, then approve selected plans. Review up to 100 at a time; later pages need separate review. Approval does not submit jobs. When asked to submit after approval, the agent calls submit_batch with the original batchId. Unapproved, expired, or changed terms are rejected per row. After a lost response, use the same submitRequestId and body rather than creating new jobs. If an older server returns individual_plan_approval_required, use individual review links from get_plan and submit_plan.

After human approval, use get_plan to check current approval and usageTerms. If terms exist, check for acceptedAt and pass the returned usageTerms.termsHash unchanged as submit_batch.acceptedTermsHash. Passing a hash does not replace consent. If plans have different terms hashes, check each plan's current terms and use submit_plan individually rather than applying one hash to the batch. Retries after response loss must retain the original body and request ID.

Requerying a batch creation request returns current pending, approved, expired, and accepted counts in approval.counts. If approval.status is partial, review only remaining pending or expired items. If approved, check current terms and submission eligibility. If submitted, provide existing job links; do not request new approval or recreate the batch. approval.required: false means no new plan approval is needed for that lookup, not that current terms, permissions, and limits have passed.

Retries and result tracking

After a lost response, preserve the original request and check acceptance with the same request ID and body. Creation uses batchRequestId; submission uses the separate submitRequestId. Do not change files, mappings, settings, or combinations under the same ID. Use a new request for changed inputs. Partial failures and quota stops are not overall success; check already accepted jobs first.

Track the source-file SHA, plan planId and planHash, row and combination numbers, jobs, execution attempts, and result provenance together. Seeds and hashes identify inputs and settings; they do not guarantee identical coordinates across GPUs and libraries.

For completed jobs, open the result details and provided structure links. Structure links still require current organization and project access. A structure file passing storage inspection is separate from successful display in the 3D viewer. Completed computation does not establish actual binding, biological function, or experimental success.

Execution and approval · Execution support · Reading results

On this page