boltz-check-status

Inspect Boltz job status and recover results via the boltz-api CLI.

5.3k|765|Updated Mar 4, 2026
One-click install
npx skills add https://github.com/openai/plugins --skill boltz-check-status
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: boltz-check-status
Source: https://github.com/openai/plugins/tree/main/plugins/boltz-api-cli/skills/boltz-check-status
Command: npx skills add https://github.com/openai/plugins --skill boltz-check-status

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve?

Long-running Boltz jobs (structure predictions, ADME, screens, designs) can outlive an agent session, leaving users unsure of job state or how to recover already-computed results without resubmitting. This Skill provides a disciplined workflow for listing, retrieving, and resuming downloads of existing Boltz jobs.

Core Features & Use Cases

  • Job Discovery: List recent jobs across all six Boltz resources (structure-and-binding, ADME, small-molecule/protein screens and designs), merged and sorted by creation time.
  • Status Retrieval: Route retrieve calls by job ID prefix (e.g., sab_pred_*, prot_des_*) and read per-resource progress counters.
  • Result Recovery: Resume interrupted downloads with download-results using the saved idempotency key as the run name, with cursor-based idempotent resume via .boltz-run.json.
  • Use Case: Your session died mid-download of a protein design job. Use this Skill to inspect local checkpoint state with download-status, recover the idempotency key via retrieve, and resume the download into the original run directory without re-submitting the job.

Quick Start

Use the boltz-check-status skill to find my Boltz job with ID prot_des_abc123, check its status, and resume downloading its results into my experiments folder.

Frequently Asked Questions about boltz-check-status

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I check the status of a Boltz job?

Run `boltz-api <resource> retrieve --id <job-id> --format json`, choosing the resource from the job ID prefix (e.g., `prot_des_*` maps to `protein:design`). If the prefix is unknown, probe each of the six resources one at a time until one succeeds.

How do I resume an interrupted Boltz results download?

Re-run `boltz-api download-results` with the same `--id`, `--name`, and `--root-dir`. The CLI reads the saved `.boltz-run.json` cursor and only pulls results past the recorded position, making the resume idempotent.

Can I recover Boltz results if I only know the job ID?

Yes. First run `retrieve` to capture the `idempotency_key`, then pass it as `--name` to `download-results`. If no idempotency key was set at submission, pick a fresh slug and download from scratch; never run `start` again.

Does the Boltz ADME endpoint support download-results?

No. ADME jobs (`adme_pred_*`) support only `list` and `retrieve`; there is no archive download step. Recover ADME scores by re-running `retrieve` and reading `output.molecules[]`, or from the local `run.json`.

Why does my structure-and-binding retrieve show only a validation error?

Failed `predictions:structure-and-binding` jobs may return only `{"code":"VALIDATION_ERROR","message":"Request validation failed"}` with no details field. This is expected behavior; inspect `input.entities` and `input.constraints` manually to diagnose.