Skip to main content
Docs

Search guides and API endpoints, for example “Idempotency-Key” or “submit job”.

    Getting started

    Run your first workflow

    Start a ready-made workflow from code, from template to downloaded results.

    Updated October 1, 2026

    On this page

    A workflow chains jobs: each step's output feeds the next step's input, and CogniChem runs the steps in order (in parallel where it can). Ready-made templates cover common problems. This page runs Screen a compound library against a target (smiles-embed-dock): it builds 3D structures from your SMILES, finds pockets on your protein, and docks every molecule into them with AutoDock Vina.

    You can also start any template without code: open the workflow gallery, pick a template, fill in its inputs, and press Run.

    1. Pick a template

    from cognichem_client import CogniChem, artifact_ref
 
client = CogniChem.from_env()  # reads COGNICHEM_API_KEY
 
for template in client.workflows.templates():
    print(f"{template.id}: {template.summary}")
 
spec = client.workflows.template("smiles-embed-dock").spec
print(spec["params"].keys())  # the inputs this template needs

    spec is a complete WorkflowSpec: its params are the inputs you supply, and its steps are the jobs. Use it as is, or change step settings before you run it. Workflows describes the format.

    2. Supply the inputs

    This template needs ligands (a list of SMILES) and target_structure (a protein structure). Files go in as artifacts: upload the PDB once, then refer to it by id.

    target = client.artifacts.upload("target.pdb", data_kind="protein_structure", data_format="pdb")
 
params = {
    "ligands": ["CCO", "c1ccccc1O", "CC(=O)Oc1ccccc1C(=O)O"],
    "target_structure": artifact_ref(target.id, "structure"),
}

    3. Validate and estimate

    Both are free. Validation checks the spec and your inputs against the job catalog; the estimate prices every step at your plan's rates.

    check = client.workflows.validate(spec, params=params)
assert check.valid, check.errors
 
estimate = client.workflows.estimate(spec, params=params)
print(f"Estimated cost: ${estimate.total:.2f}")

    4. Run it

    run = client.workflows.runs.run(
    "first-screen",
    spec,
    params=params,
    max_run_cost=estimate.total * 1.5,  # pause once charges reach this
)
print(run.status)  # completed, failed, cancelled, or paused

    Starting a run holds the estimate in your wallet; each step is charged as it finishes, and whatever is left of the hold is released when the run ends. Once the run's charges reach max_run_cost, it pauses after that step so you can look at the results before spending more; client.workflows.runs.resume(run.id) continues it.

    runs.run waits until the run stops. To start a run and come back later, use client.workflows.runs.create(...), then runs.get(run_id) or the completion events.

    5. Get the results

    Each step's outputs are stored as artifacts. List them, then download whole result zips or single records:

    for item in client.workflows.runs.artifacts(run.id).items:
    print(item.step_key, item.port, item.artifact_id, item.record_count)

    Artifacts explains records, downloads, and how long results are kept.

    Next