# Cancel a reply
Source: https://docs.biomni.phylo.bio/api-reference/pages/cancel-reply

api-reference/openapi.json POST /experimental/tasks/{task_id}/messages/{message_id}/cancel
Stop the agent while it is writing this reply.

Cancels the task the message belongs to, since the agent works on one reply at a time. Equivalent to `POST /tasks/{task_id}/cancel`.


# Cancel a task
Source: https://docs.biomni.phylo.bio/api-reference/pages/cancel-task

api-reference/openapi.json POST /experimental/tasks/{task_id}/cancel
Stop a running task.

The body is optional. Omit it, or send `"force": false`, for a graceful stop. `"force": true` cancels immediately.


# Create a project
Source: https://docs.biomni.phylo.bio/api-reference/pages/create-project

api-reference/openapi.json POST /projects
Create a project to group related tasks and files.

A project groups related tasks and holds the files they read and write.


# Delete a project
Source: https://docs.biomni.phylo.bio/api-reference/pages/delete-project

api-reference/openapi.json DELETE /projects/{project_id}
Delete a project and everything in it.

Its tasks and files become inaccessible immediately. This cannot be undone.


# Delete a task
Source: https://docs.biomni.phylo.bio/api-reference/pages/delete-task

api-reference/openapi.json DELETE /experimental/tasks/{task_id}
Delete a task and its messages.

The task becomes inaccessible immediately. Files the agent produced belong to the project and are not deleted.


# Download a file
Source: https://docs.biomni.phylo.bio/api-reference/pages/download-file

api-reference/openapi.json GET /experimental/files/{file_id}/content
Download an input or result file.

Returns `302 Found` with a `Location` header pointing at a download link that expires in about 5 minutes. Use a client that follows redirects, such as `curl -L`.


# Download a result
Source: https://docs.biomni.phylo.bio/api-reference/pages/download-result

api-reference/openapi.json GET /experimental/tasks/{task_id}/results/{result_id}/download
Get a fresh download link for one of a task's result files.

Returns a new `download_url` for one result file. The URLs returned by `GET /tasks/{task_id}/results` are short-lived; call this when one has expired.


# Finalize an upload
Source: https://docs.biomni.phylo.bio/api-reference/pages/finalize-upload

api-reference/openapi.json POST /experimental/files/{file_id}/finalize
Finish an upload so the file becomes available to the agent.

Call this after sending the bytes to the `upload_url` from `POST /experimental/files`. Until then, the file is stored but not visible to tasks in the project.


# Get a file
Source: https://docs.biomni.phylo.bio/api-reference/pages/get-file

api-reference/openapi.json GET /experimental/files/{file_id}
Get metadata for one uploaded file.

Returns metadata, not contents. Download the file with `GET /experimental/files/{id}/content`.


# Get a message
Source: https://docs.biomni.phylo.bio/api-reference/pages/get-message

api-reference/openapi.json GET /experimental/tasks/{task_id}/messages/{message_id}
Look up a single message by id.

Works for a message you sent, an agent reply, or the `message_id` returned by a completed scientific review. A reply in progress has `status: "running"`; read it again for the content written since.


# Get multipart part URLs
Source: https://docs.biomni.phylo.bio/api-reference/pages/get-part-urls

api-reference/openapi.json POST /experimental/files/{file_id}/parts
Get upload URLs for a multipart upload's parts.

Used only when `POST /experimental/files` returned `upload_type: "multipart"`. Pass the `upload_id` from that response and the part numbers you are about to upload; each one gets a PUT URL.

You can request parts in batches. PUT each chunk to its URL, keep the `ETag` from each response, then pass every `{part_number, etag}` to `POST /experimental/files/{file_id}/finalize`.


# Get a project
Source: https://docs.biomni.phylo.bio/api-reference/pages/get-project

api-reference/openapi.json GET /projects/{project_id}
Get a project by id.

# Get a task
Source: https://docs.biomni.phylo.bio/api-reference/pages/get-task

api-reference/openapi.json GET /experimental/tasks/{task_id}
Get a task, its status, and any scientific reviews of it.

A task settles at `completed`, `failed`, or `cancelled`. Read this endpoint again for its current status.

| `status` | Meaning |
| - | - |
| `idle` | No message has been sent yet |
| `running` | The agent is working |
| `completed` | The agent finished this turn and no background work is running |
| `failed` | The latest agent message carries an `error`, or the task stopped because your workspace's prepaid credits ran out |
| `cancelled` | You stopped the task |

When a task stops because your workspace's prepaid credits ran out, `status` is `failed` and `error` says why, with `code` `payment_required`. Send a new message after adding credits to continue the task.

`reviews` holds the [scientific reviews](/api-reference/pages/review-task) of this task, each with its `status`, the `message_id` of the message holding the findings, and `error_message` on a failure. A review appears once it has written its findings.


# List files
Source: https://docs.biomni.phylo.bio/api-reference/pages/list-files

api-reference/openapi.json GET /experimental/files
List the files uploaded to a project.

Returns metadata, not contents. Download a file with `GET /experimental/files/{id}/content`. Pass a file's `id` in `file_ids` on `POST /experimental/tasks/{id}/messages` to attach it to a task.


# List messages
Source: https://docs.biomni.phylo.bio/api-reference/pages/list-messages

api-reference/openapi.json GET /experimental/tasks/{task_id}/messages
List a task's messages in order, oldest first.

Your messages have `role: "user"` and the agent's have `role: "assistant"`. Each agent reply is a single message whose `content[]` holds the whole reply: text, tool calls, and results. If Biomni's safeguards redirected or stopped the agent, the reply also includes a `system_notice` block saying so. A reply still in progress has `status: "running"` with the content so far.

`limit` (default 200, max 500) bounds the underlying events read, not the messages returned, so expect fewer messages than `limit`. The first page is the most recent stretch of the conversation.


# List projects
Source: https://docs.biomni.phylo.bio/api-reference/pages/list-projects

api-reference/openapi.json GET /projects
List your projects, newest first.

A default project exists for unfiled tasks.


# List task results
Source: https://docs.biomni.phylo.bio/api-reference/pages/list-results

api-reference/openapi.json GET /experimental/tasks/{task_id}/results
List the files the agent produced under a task, each with a download link.

Lists every file the agent has written so far, including files written while the task is still running. `with_urls` (default `true`) attaches a download URL to each file.

An unknown `task_id` returns `404`, so an empty `data` array means the task produced no files.


# List skills
Source: https://docs.biomni.phylo.bio/api-reference/pages/list-skills

api-reference/openapi.json GET /experimental/skills
List the skills you can run in a task.

A skill is a packaged workflow from the Biomni catalog, such as a grounded literature review or a genome-editing design routine. This returns both built-in skills and your own.

Pass an entry's `id` or `name` as `skill` on `POST /tasks/{id}/messages` to run it. `owner_type` is `system` for a built-in skill and `user` for one of your own.


# List tasks
Source: https://docs.biomni.phylo.bio/api-reference/pages/list-tasks

api-reference/openapi.json GET /experimental/tasks
List a project's tasks, newest first.

# Run a scientific review
Source: https://docs.biomni.phylo.bio/api-reference/pages/review-task

api-reference/openapi.json POST /experimental/tasks/{task_id}/review
Check a completed task's analysis for scientific accuracy.

A reviewer agent re-reads a completed task's analysis and checks it for scientific accuracy, correct use of the data, unsupported claims, and stated limitations. A task that is `idle` or still `running` has nothing to review.

The review runs in the background. This call returns immediately with `status: "running"` and does not return the review itself. When it finishes, a new entry appears in `reviews` on `GET /tasks/{task_id}`. Read the findings with `GET /tasks/{task_id}/messages/{message_id}` using that entry's exact `message_id`.

Calling this while a review is running returns the running state. Calling it after a review finishes starts a new one that replaces the previous result.


# Send a message
Source: https://docs.biomni.phylo.bio/api-reference/pages/send-message

api-reference/openapi.json POST /experimental/tasks/{task_id}/messages
Send a message to the agent and get its reply.

Sends to an existing task. Create one with `POST /tasks` first. If the agent is still working, the response holds the reply so far; the rest arrives on `GET /tasks/{task_id}/messages/{id}`.

### Model tier

`model` sets the tier for a new task:

* `standard`: the default balance of speed and capability
* `fast`: lower latency on a lighter model
* `max`: the highest-capability model

An unknown value returns `422`. The tier is fixed when the task is created, so it is ignored when you pass `task_id`. `POST /tasks` does not accept a tier.

### Skills

`skill` runs a skill on your message. Pass an id or name from [List skills](/api-reference/pages/list-skills); your `content` is the input. An unknown skill returns `404`. Ignored when you pass `task_id`.

### Attached files

`file_ids` must reference files already finalized in the task's project. A file that cannot be read is skipped: the message still sends, without that attachment.


# Start a task
Source: https://docs.biomni.phylo.bio/api-reference/pages/start-task

api-reference/openapi.json POST /experimental/tasks
Create an idle task inside a project, or start it immediately with initial messages.

The task shares the project's files and starts in `idle`. It stays idle until you send the first message with `POST /tasks/{id}/messages`, which moves it to `running`. Read its status with `GET /tasks/{id}` and stop it with `POST /tasks/{id}/cancel`.

`model` picks the tier the agent runs on. It is fixed when the task is created and cannot be changed afterwards, so start a new task to work on a different tier. Omit it to take the default.

Pass `initial_messages` to skip that second call: the messages are delivered to the task in the order you list them and the agent starts on the last one, reading the ones before it as the conversation so far. The task comes back as `running`.


# Update a project
Source: https://docs.biomni.phylo.bio/api-reference/pages/update-project

api-reference/openapi.json PUT /projects/{project_id}
Rename a project or edit its description.

Only the fields you send change. Send an empty string, such as `"description": ""`, to clear a field.


# Upload a file
Source: https://docs.biomni.phylo.bio/api-reference/pages/upload-file

api-reference/openapi.json POST /experimental/files
Start an upload so the agent can use the file in a task.

Uploads go directly to cloud storage. The API returns an upload target and never receives the bytes. The response's `upload_type` selects the flow and is chosen from the `size_bytes` you declare.

### `upload_type: "single"`

1. `POST /experimental/files` returns a `file_id`, an `upload_url`, and the `fields` to send with the bytes.
2. POST the bytes to `upload_url` as multipart form-data, with every key in `fields` included as a form field. Success returns `204 No Content`.
3. `POST /experimental/files/{file_id}/finalize` with an empty body.

### `upload_type: "multipart"`

1. `POST /experimental/files` returns a `file_id`, an `upload_id`, a `part_size_bytes`, and a `part_count`.
2. Split the file into `part_count` chunks of `part_size_bytes`. The last chunk is the remainder.
3. `POST /experimental/files/{file_id}/parts` with the `upload_id` and the part numbers you want, which returns a PUT URL per part. You can request them in batches.
4. PUT each chunk to its URL and keep the `ETag` response header for that part number.
5. `POST /experimental/files/{file_id}/finalize` with `{ "upload_id": "…", "parts": [{ "part_number": 1, "etag": "…" }, … ] }`.

Once finalized, attach the `file_id` to a task with `file_ids` on `POST /experimental/tasks/{id}/messages`.


# Authentication
Source: https://docs.biomni.phylo.bio/api/authentication

Create an API key and authenticate your requests to the Phylo API

## Plan and billing

To use the API, your workspace must be on a Pro or Team plan.

API usage draws only on your workspace's prepaid balance. It does not use your
daily credit allowance. To add funds, open **Settings → Billing** in
[Biomni Lab](https://biomni.phylo.bio). If the prepaid balance is empty, the API
refuses requests that start work and returns a `400` error with the code
`payment_required`.

## Create an API key

A key acts within the workspace it was created in, with your own permissions in
that workspace.

1. In [Biomni Lab](https://biomni.phylo.bio), open **Settings → API Keys**.
2. Click **Create key**, give it a name (e.g. `Batch analysis pipeline`), and
   optionally an expiration.

> [!WARNING]
>
> Treat your API key like a password. Anyone with it can act as you within that
> workspace.

## Base URL

For the self-serve platform, use:

```
https://api.phylo.bio/v1
```

If you're an Enterprise customer, contact your Phylo representative for your
API base URL.

## Authenticate a request

Send the key as a **bearer token** in the `Authorization` header:

```bash curl theme={null}
curl https://api.phylo.bio/v1/projects \
  -H "Authorization: Bearer $PHYLO_API_KEY"
```

```python Python theme={null}
import os, requests

BASE = "https://api.phylo.bio/v1"
headers = {"Authorization": f"Bearer {os.environ['PHYLO_API_KEY']}"}

resp = requests.get(f"{BASE}/projects", headers=headers)
resp.raise_for_status()
print(resp.json())
```

## Revoke a key

From **Settings → API Keys**, **Revoke** disables a key immediately and
permanently.

Keys can carry an expiration. An expired key stops working automatically.

## Next steps

> [card] [Quickstart](/api/quickstart)
>
> Key → project → task → results, end to end.

> [card] [Errors](/api/errors)
>
> Status codes, error handling, and retries.


# Errors
Source: https://docs.biomni.phylo.bio/api/errors

Status codes and error responses for the Phylo API

All errors return the same body:

```json theme={null}
{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "code": "not_found",
    "message": "Project prj_01xxxxxxxxxxxxxxxxxxxxxx not found."
  }
}
```

`code` is stable and machine-readable; `message` is not. On validation errors,
`error.param` names the offending field.

| Status | `error.type` | Meaning |
| - | - | - |
| `400` | `invalid_request_error` | Required fields are missing or invalid, or no prepaid credits are available (`code` `payment_required`). API usage draws on your workspace's prepaid credits only; a workspace admin on a Pro or Team plan can add them in **Settings → Billing**. |
| `401` | `authentication_error` | The key is missing, malformed, revoked, or expired. Check the `Authorization` header and the key's status in **Settings → API Keys**. |
| `403` | `permission_error` | The key is valid but lacks permission. A key acts with your permissions, in its own workspace. |
| `404` | `invalid_request_error` | The project, task, or file id does not exist in this workspace. |
| `422` | `invalid_request_error` | The request body failed validation. `error.param` names the field. |
| `429` | `rate_limit_error` | Too many requests (see [Rate limits](/api/rate-limits)), or too many tasks running at once (`code` `too_many_running_tasks`). |
| `5xx` | `api_error` | Server error. |


# Quickstart
Source: https://docs.biomni.phylo.bio/api/quickstart

From an API key to running an agent task and downloading its results

## Prerequisites

* [A Phylo account](https://biomni.phylo.bio) on a Pro or Team plan, with a
  prepaid balance. API usage draws only on the prepaid balance, not on your
  daily credit allowance. See [Plan and billing](/api/authentication#plan-and-billing).
* [An API key](/api/authentication)

The steps below assume your key is set as `PHYLO_API_KEY`:

```bash theme={null}
export PHYLO_API_KEY="<your-api-key>"
```

To test your API key, try listing projects:

```bash theme={null}
curl https://api.phylo.bio/v1/projects \
  -H "Authorization: Bearer $PHYLO_API_KEY"
```

Note that `https://api.phylo.bio/v1` is the self-serve base URL. If you're an
Enterprise customer, contact your Phylo representative for your API base URL.

## Using a Biomni agent

**1. Create a project**

To get started, let's create a project. Projects group related tasks and
files:

```bash theme={null}
PROJECT_ID=$(curl -s -X POST https://api.phylo.bio/v1/projects \
  -H "Authorization: Bearer $PHYLO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title": "BRCA1 variant workup"}' | jq -r '.id')
```

This returns something like:

```json theme={null}
{
  "id": "prj_014OwAG97UY0UfcHlLHQRnKO",
  "type": "project",
  "title": "BRCA1 variant workup",
  "description": "",
  "created_at": "2026-08-12T21:21:01.919692Z",
  "updated_at": "2026-08-12T21:21:01.919698Z"
}
```

**2. Start a task**

Now that we have a project, let's start a task. A task is one conversation
with the agent:

```bash theme={null}
TASK_ID=$(curl -s -X POST https://api.phylo.bio/v1/experimental/tasks \
  -H "Authorization: Bearer $PHYLO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "project_id": "'"$PROJECT_ID"'",
    "title": "BRCA1 variant workup",
    "auto_mode": true,
    "initial_messages": [
      {"role": "user", "content": "Look up the ClinVar status of BRCA1 variants rs80357065, rs28897696, and rs80357382, and write a short markdown summary report."}
    ]
  }' | jq -r '.id')
```

This returns something like:

```json theme={null}
{
  "id": "tsk_017ilCeuDpMWTSH9Ah1syUGJ",
  "type": "task",
  "created_at": "2026-08-12T21:21:02.815306Z",
  "status": "running",
  "project_id": "prj_014OwAG97UY0UfcHlLHQRnKO",
  "title": "BRCA1 variant workup",
  "platform": "api"
}
```

**3. Check the status**

Now that the agent is working, let's check on it. `status` moves from
`running` to `completed`, `failed`, or `cancelled`:

```bash theme={null}
curl -s https://api.phylo.bio/v1/experimental/tasks/$TASK_ID \
  -H "Authorization: Bearer $PHYLO_API_KEY" | jq -r '.status'
```

The full record returns something like:

```json theme={null}
{
  "id": "tsk_017ilCeuDpMWTSH9Ah1syUGJ",
  "type": "task",
  "created_at": "2026-08-12T21:21:02.815000Z",
  "status": "completed",
  "project_id": "prj_014OwAG97UY0UfcHlLHQRnKO",
  "title": "BRCA1 variant workup",
  "platform": "api",
  "reviews": []
}
```

Agent tasks can run for hours, so design for long-running work rather than
blocking a single request on the result.

**4. Download the results**

Now that the task is done, let's collect its output. Save the files the
agent wrote:

```bash theme={null}
curl -s "https://api.phylo.bio/v1/experimental/tasks/$TASK_ID/results?with_urls=true" \
  -H "Authorization: Bearer $PHYLO_API_KEY" \
  | jq -r '.data[] | .download_url + " -o " + .name' \
  | xargs -L1 curl -s
```

The results list returns something like:

```json theme={null}
{
  "type": "list",
  "data": [
    {
      "type": "result_file",
      "result_id": "res_016YNAz7cvmPXcqvGoR1U57t",
      "name": "BRCA1_ClinVar_variant_summary.md",
      "size_bytes": 6149,
      "mime_type": "text/markdown",
      "message_id": null,
      "created_at": "2026-08-12T21:23:32Z",
      "download_url": "https://files.s3.us-west-2.amazonaws.com/...?X-Amz-Signature=..."
    }
  ],
  "has_more": false,
  "first_id": "res_016YNAz7cvmPXcqvGoR1U57t",
  "last_id": "res_016YNAz7cvmPXcqvGoR1U57t"
}
```

`download_url` is presigned and short-lived, so fetch it soon after listing.

**5. Send a message**

Now that we have results, let's keep the conversation going. Ask a
follow-up in the same task:

```bash theme={null}
curl -s -X POST https://api.phylo.bio/v1/experimental/tasks/$TASK_ID/messages \
  -H "Authorization: Bearer $PHYLO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"content": "Which of those three variants has the strongest PARP inhibitor evidence?"}'
```

This returns your message and the agent's reply so far:

```json theme={null}
{
  "type": "message_result",
  "user_message": {
    "id": "msg_f6872d1e0fb242fd",
    "type": "message",
    "task_id": "tsk_017ilCeuDpMWTSH9Ah1syUGJ",
    "created_at": "2026-08-12T21:26:51.413000Z",
    "role": "user",
    "content": [
      {"type": "text", "text": "Which of those three variants has the strongest PARP inhibitor evidence?"}
    ],
    "platform": "api"
  },
  "assistant_message": {
    "id": "msg_0e9eb143c44838c4",
    "type": "message",
    "task_id": "tsk_017ilCeuDpMWTSH9Ah1syUGJ",
    "created_at": "2026-08-12T21:26:28.611000Z",
    "role": "assistant",
    "content": [
      {
        "type": "text",
        "text": "Searching PubMed and CIViC for PARP inhibitor and functional HDR evidence for each of the three BRCA1 variants."
      },
      {
        "type": "tool_result",
        "tool_use_id": "toolu_01BmvmDbqJwohi5WxdBoWk17",
        "content": "{\"delivered\": true}"
      }
    ],
    "status": "running",
    "platform": "api",
    "input": {"user_message_id": "msg_f6872d1e0fb242fd", "file_ids": []}
  }
}
```

## Where to go next

Congratulations, you just ran a Biomni agent! That loop is the foundation, and
there is a lot more the agent can do:

* [Upload a file](/api-reference/pages/upload-file) and attach it to a message
  with `file_ids`, so the agent works on your own data.
* [Run a scientific review](/api-reference/pages/review-task) to have a reviewer
  agent check a finished task's analysis for scientific accuracy.
* [Start a task](/api-reference/pages/start-task) with `plan_mode`, and the
  agent writes a plan for you to approve before it starts work.
* [Errors](/api/errors) covers status codes, retries, and backoff.


# Rate limits
Source: https://docs.biomni.phylo.bio/api/rate-limits

Request limits for each Phylo API endpoint

Limits are per API key, per minute.

| Endpoints | Requests per minute |
| - | - |
| `POST /v1/experimental/tasks` `POST /v1/experimental/tasks/{task_id}/messages` `POST /v1/experimental/tasks/{task_id}/review` | 60 |
| `POST /v1/experimental/tasks/{task_id}/cancel` `POST /v1/experimental/tasks/{task_id}/messages/{message_id}/cancel` `DELETE /v1/experimental/tasks/{task_id}` | 120 |
| `POST /v1/projects` `PUT /v1/projects/{project_id}` `DELETE /v1/projects/{project_id}` | 60 |
| `POST /v1/experimental/files` `POST /v1/experimental/files/{file_id}/parts` `POST /v1/experimental/files/{file_id}/finalize` | 300 |
| `GET /v1/experimental/tasks/{task_id}/results` | 60 |
| `GET /v1/experimental/files/{file_id}/content` `GET /v1/experimental/tasks/{task_id}/results/{result_id}/download` | 300 |
| All other `GET` endpoints | 600 |

At most 10 tasks can run at once.

Each response includes these headers:

| Header | Meaning |
| - | - |
| `phylo-ratelimit-requests-limit` | Requests allowed per minute |
| `phylo-ratelimit-requests-remaining` | Requests left this minute |
| `phylo-ratelimit-requests-reset` | When the count resets (RFC 3339, UTC) |

Over the limit, the API returns `429` with `error.type` `rate_limit_error` and a `retry-after` header in seconds.


# Running batch analyses in parallel
Source: https://docs.biomni.phylo.bio/api/recipes/batch-analysis

Run one analysis on many datasets in parallel, then grade each result in a second task

[Running and grading an analysis](/api/recipes/running-an-analysis) runs one
analysis task and grades it. This recipe scales that pattern out: it starts the same analysis
on five datasets at once, and grades each result in its own task as soon as the
analysis finishes.

The analysis asks whether TP53 mutation predicts overall survival in five public
TCGA PanCancer Atlas studies on cBioPortal (lung, colorectal, breast, melanoma,
and stomach cancer). Each analysis writes `report.md` and `result.json`. Each
grading task reads only those two files and scores them against a 100-point
rubric.

![Task list in the API demo project with five TP53 survival tasks and a gene list review task, all running](https://mintcdn.com/phylo/liKXOE1vbHNl7uvD/images/api-recipe-batch-tasks.png?fit=max\&auto=format\&n=liKXOE1vbHNl7uvD\&q=85\&s=5c3cf9254524b86b94b00382ff69cace)

All six tasks in a project, created through the API and running in parallel: five TP53 survival analyses and a gene list review.

## Prerequisites

* [An API key](/api/authentication)
* Python 3.10 or later with the `requests` package
* `phylo_client.py` from [Building a Python client](/api/recipes/wrapping-the-api-in-python),
  saved beside your script

Install `requests`, then set your API key:

```bash theme={null}
python -m pip install requests
export PHYLO_API_KEY="<your-api-key>"
```

The script uses `https://api.phylo.bio/v1`. If you're an Enterprise customer,
set the `PHYLO_BASE_URL` environment variable to the API base URL shared by your
Phylo representative.

By default, the script creates a project called "API demo". To use an existing
project instead, set `PHYLO_PROJECT_ID` to its ID.

## How it works

### Start one analysis per dataset

`run_analysis()` creates a task with the analysis prompt for one study, waits
for it to finish, and downloads its result files. It pins the model with
`model="max"` and `disable_fallbacks=True`, so every dataset is analyzed by the
same model. `auto_mode=True` lets the task run to completion without stopping
for a person to answer questions or approve its plan.

```python theme={null}
def run_analysis(phylo, project_id, study):
    task = phylo.create_task(
        project_id=project_id,
        title=f"TP53 survival: {study}",
        initial_messages=[
            {"role": "user", "content": ANALYSIS_PROMPT.format(study=study)}
        ],
        model="max",
        disable_fallbacks=True,
        auto_mode=True,
    )
    print(f"[{study}] analysis task {task['id']}")
    phylo.wait_for_task(task["id"], poll_interval_seconds=60)
    return phylo.download_results(task["id"], Path("analysis-results") / study)
```

### Grade each result in a second task

`grade_analysis()` uploads the analysis output to the project and starts a
grading task. The files are uploaded under study-specific names, so every
grading task in the shared project reads only its own study's files. The
grading task writes `score.json`, which the script downloads.

```python theme={null}
def grade_analysis(phylo, project_id, study, results_dir):
    # Upload the analysis output under study-specific names so every grading
    # task in the shared project reads only its own files.
    prefix = f"{study}__"
    for name in ("report.md", "result.json"):
        staged = results_dir / f"{prefix}{name}"
        shutil.copyfile(results_dir / name, staged)
        phylo.upload_file(project_id, staged)

    task = phylo.create_task(
        project_id=project_id,
        title=f"Grade TP53 survival: {study}",
        initial_messages=[
            {
                "role": "user",
                "content": GRADING_PROMPT.format(study=study, prefix=prefix),
            }
        ],
        model="max",
        disable_fallbacks=True,
        auto_mode=True,
    )
    print(f"[{study}] grading task {task['id']}")
    phylo.wait_for_task(task["id"], poll_interval_seconds=60)
    grade_dir = phylo.download_results(task["id"], results_dir / "grade")
    return json.loads((grade_dir / "score.json").read_text())
```

### Run every dataset in parallel

`main()` runs each study in its own thread. A study's grading task starts as
soon as its analysis finishes, without waiting for the other studies. When all
studies are done, the script prints a summary table.

```python theme={null}
def run_study(project_id, study):
    phylo = PhyloClient()  # one HTTP session per thread
    results_dir = run_analysis(phylo, project_id, study)
    score = grade_analysis(phylo, project_id, study, results_dir)
    result = json.loads((results_dir / "result.json").read_text())
    return study, result, score


def main():
    phylo = PhyloClient()
    project_id = (
        os.getenv("PHYLO_PROJECT_ID")
        or phylo.create_project(title="API demo")["id"]
    )

    # At most 10 tasks run at once; each study runs one task at a time.
    with ThreadPoolExecutor(max_workers=len(STUDIES)) as pool:
        outcomes = list(pool.map(lambda s: run_study(project_id, s), STUDIES))

    print(f"\n{'study':34} {'HR (95% CI)':22} {'cox p':>8} {'score':>6}")
    for study, result, score in outcomes:
        ci = (
            f"{result['cox_hr']:.2f} "
            f"({result['cox_hr_ci_low']:.2f}-{result['cox_hr_ci_high']:.2f})"
        )
        print(f"{study:34} {ci:22} {result['cox_p']:>8.3g} {score['total_score']:>6}")
```

At most 10 tasks can run at once (see [Rate limits](/api/rate-limits)). Each
study runs one task at a time, so this script never runs more than five tasks.
If you add more datasets, lower `max_workers` or handle `429` responses.

## Run the script

Save the [full script](#full-script) as `batch_analysis.py` beside
`phylo_client.py`, then run:

```bash theme={null}
python batch_analysis.py
```

Each study's analysis output is saved under `analysis-results/<study>/`, and
its grading output under `analysis-results/<study>/grade/`.

## Example results

All five analyses scored 100/100.

| Study | Patients | TP53-mutant | Adjusted Cox HR (95% CI) | Cox p | Score |
| - | - | - | - | - | - |
| BRCA | 1,066 | 346 | 1.48 (1.04-2.10) | 0.029 | 100 |
| COADREAD | 530 | 309 | 0.81 (0.54-1.22) | 0.324 | 100 |
| LUAD | 502 | 251 | 1.16 (0.86-1.58) | 0.329 | 100 |
| SKCM | 423 | 70 | 0.80 (0.54-1.20) | 0.285 | 100 |
| STAD | 431 | 212 | 0.99 (0.73-1.36) | 0.972 | 100 |

Every task stays in the project, so you can open any run in Biomni to read
the agent's work or ask follow-up questions.

![Agent summary of the BRCA TP53 survival analysis with result files listed in the Results panel](https://mintcdn.com/phylo/liKXOE1vbHNl7uvD/images/api-recipe-batch-result.png?fit=max\&auto=format\&n=liKXOE1vbHNl7uvD\&q=85\&s=c19e869ac740cbb9d23ba5b3bd80db6f)

A finished analysis (BRCA): the agent's summary, with report.md and result.json in the Results panel.

![Grading table for the BRCA analysis with a score of 100 out of 100 and a rationale per criterion](https://mintcdn.com/phylo/liKXOE1vbHNl7uvD/images/api-recipe-batch-grade.png?fit=max\&auto=format\&n=liKXOE1vbHNl7uvD\&q=85\&s=0e06bac9b010b18abe0ef6fb65917f9e)

The BRCA grading task: a score and a reason for each rubric criterion.

## Adapting this for your analysis

* Replace `STUDIES` with your datasets, and `ANALYSIS_PROMPT` and
  `GRADING_PROMPT` with your analysis and rubric.
* Ask for a machine-readable output file with fixed keys, as `result.json`
  does here, so you can compare runs without parsing prose.
* Keep the grader blind to everything except the files it grades, so its
  score reflects only the output.

## Full script

```python batch_analysis.py theme={null}
"""Batch analysis: run one analysis across many datasets, then grade each
result in a second task."""

import json
import os
import shutil
from concurrent.futures import ThreadPoolExecutor
from pathlib import Path

from phylo_client import PhyloClient

# Five public TCGA PanCancer Atlas studies on cBioPortal.
STUDIES = [
    "luad_tcga_pan_can_atlas_2018",
    "coadread_tcga_pan_can_atlas_2018",
    "brca_tcga_pan_can_atlas_2018",
    "skcm_tcga_pan_can_atlas_2018",
    "stad_tcga_pan_can_atlas_2018",
]

ANALYSIS_PROMPT = """
Test whether TP53 mutation status is associated with overall survival in the
cBioPortal study {study}. Download the study's mutation and clinical data from
cBioPortal yourself.

- Call a patient TP53-mutant if they carry any nonsynonymous TP53 mutation.
- Compare overall survival with Kaplan-Meier curves and a log-rank test.
- Fit a Cox model for TP53 status adjusted for age at diagnosis and AJCC
  pathologic stage.

Save two files under /mnt/results/:

1. report.md: cohort, definitions, methods, code, results, interpretation, and
   limitations.
2. result.json, raw JSON with exactly these keys: study_id, n_patients,
   n_tp53_mutant, logrank_p, cox_hr, cox_hr_ci_low, cox_hr_ci_high, cox_p,
   conclusion.
""".strip()

GRADING_PROMPT = """
Grade the TP53 overall-survival analysis of {study} in the project files
{prefix}report.md and {prefix}result.json. Judge only those two files. Do not
redo the analysis or read any other file.

Score each criterion and explain why:
1. Cohort and TP53 definition (20): nonsynonymous mutations only, patients
   without survival data excluded, counts reported.
2. Survival analysis (25): Kaplan-Meier plus log-rank test, done correctly.
3. Adjusted model (25): Cox model with age and stage, hazard ratio, 95% CI and
   p-value reported.
4. Consistency (15): result.json matches the numbers in report.md.
5. Interpretation (15): conclusion follows from the numbers, limitations noted.

Save raw JSON (no code fence) at /mnt/results/score.json:
{{"study_id": "{study}", "total_score": 0,
  "criteria": [{{"criterion": "...", "points": 0, "max_points": 0, "reason": "..."}}],
  "summary": "..."}}
""".strip()


def run_analysis(phylo, project_id, study):
    task = phylo.create_task(
        project_id=project_id,
        title=f"TP53 survival: {study}",
        initial_messages=[
            {"role": "user", "content": ANALYSIS_PROMPT.format(study=study)}
        ],
        model="max",
        disable_fallbacks=True,
        auto_mode=True,
    )
    print(f"[{study}] analysis task {task['id']}")
    phylo.wait_for_task(task["id"], poll_interval_seconds=60)
    return phylo.download_results(task["id"], Path("analysis-results") / study)


def grade_analysis(phylo, project_id, study, results_dir):
    # Upload the analysis output under study-specific names so every grading
    # task in the shared project reads only its own files.
    prefix = f"{study}__"
    for name in ("report.md", "result.json"):
        staged = results_dir / f"{prefix}{name}"
        shutil.copyfile(results_dir / name, staged)
        phylo.upload_file(project_id, staged)

    task = phylo.create_task(
        project_id=project_id,
        title=f"Grade TP53 survival: {study}",
        initial_messages=[
            {
                "role": "user",
                "content": GRADING_PROMPT.format(study=study, prefix=prefix),
            }
        ],
        model="max",
        disable_fallbacks=True,
        auto_mode=True,
    )
    print(f"[{study}] grading task {task['id']}")
    phylo.wait_for_task(task["id"], poll_interval_seconds=60)
    grade_dir = phylo.download_results(task["id"], results_dir / "grade")
    return json.loads((grade_dir / "score.json").read_text())


def run_study(project_id, study):
    phylo = PhyloClient()  # one HTTP session per thread
    results_dir = run_analysis(phylo, project_id, study)
    score = grade_analysis(phylo, project_id, study, results_dir)
    result = json.loads((results_dir / "result.json").read_text())
    return study, result, score


def main():
    phylo = PhyloClient()
    project_id = (
        os.getenv("PHYLO_PROJECT_ID")
        or phylo.create_project(title="API demo")["id"]
    )

    # At most 10 tasks run at once; each study runs one task at a time.
    with ThreadPoolExecutor(max_workers=len(STUDIES)) as pool:
        outcomes = list(pool.map(lambda s: run_study(project_id, s), STUDIES))

    print(f"\n{'study':34} {'HR (95% CI)':22} {'cox p':>8} {'score':>6}")
    for study, result, score in outcomes:
        ci = (
            f"{result['cox_hr']:.2f} "
            f"({result['cox_hr_ci_low']:.2f}-{result['cox_hr_ci_high']:.2f})"
        )
        print(f"{study:34} {ci:22} {result['cox_p']:>8.3g} {score['total_score']:>6}")


if __name__ == "__main__":
    main()
```


# Reviewing a gene list
Source: https://docs.biomni.phylo.bio/api/recipes/gene-list-review

Send a gene list for a first-pass review, then hand what it flags to a scientist to check

This recipe sends a gene list to Biomni for a first-pass review and turns the
genes it flags into a checklist for a scientist. The checklist links back to
the task, so the scientist can open it in Biomni and keep the conversation
going.

The example list is 15 hits from a genome-wide CRISPR knockout screen for
vemurafenib resistance in A375 melanoma cells. For each gene, the agent checks
whether its symbol is current, whether it is expressed in melanoma lines,
whether there is published evidence linking its loss to MAPK-inhibitor
resistance, and whether it could be a screen artifact. It returns a verdict of
`plausible` or `flag` for each gene, with reasons and sources.

## Prerequisites

* [An API key](/api/authentication)
* Python 3.10 or later with the `requests` package
* `phylo_client.py` from [Building a Python client](/api/recipes/wrapping-the-api-in-python),
  saved beside your script

Install `requests`, then set your API key:

```bash theme={null}
python -m pip install requests
export PHYLO_API_KEY="<your-api-key>"
```

The script uses `https://api.phylo.bio/v1`. If you're an Enterprise customer,
set the `PHYLO_BASE_URL` environment variable to the API base URL shared by your
Phylo representative.

By default, the script creates a project called "API demo". To use an existing
project instead, set `PHYLO_PROJECT_ID` to its ID.

## How it works

`main()` creates the review task with `auto_mode=True`, waits for it to
finish, and downloads `review.json`. It then writes every flagged gene, with
the agent's reasons and sources, to `scientist_checklist.md`.

```python theme={null}
def main():
    phylo = PhyloClient()
    project_id = (
        os.getenv("PHYLO_PROJECT_ID")
        or phylo.create_project(title="API demo")["id"]
    )

    task = phylo.create_task(
        project_id=project_id,
        title="Gene list review: vemurafenib resistance screen",
        initial_messages=[
            {"role": "user", "content": REVIEW_PROMPT.format(genes=", ".join(GENES))}
        ],
        auto_mode=True,
    )
    print(f"Review task: {task['id']}")
    phylo.wait_for_task(task["id"], poll_interval_seconds=60)

    results_dir = phylo.download_results(task["id"], Path("gene-review") / task["id"])
    review = json.loads((results_dir / "review.json").read_text())
    flagged = [entry for entry in review if entry["verdict"] == "flag"]

    task_url = f"{WEB_BASE}/projects/{project_id}/tasks/{task['id']}"
    checklist = results_dir / "scientist_checklist.md"
    write_checklist(checklist, task_url, flagged)
    print(f"{len(flagged)} of {len(review)} genes flagged for a scientist to check.")
    print(f"Checklist: {checklist}")
    print(f"Task: {task_url}")
```

`write_checklist()` turns the flagged genes into a Markdown checklist with a
link to the task:

```python theme={null}
def write_checklist(path, task_url, flagged):
    lines = [
        "# Gene list review: genes to check",
        "",
        f"Biomni's first-pass review: {task_url}",
        "Reply in that task to ask Biomni follow-up questions about any gene.",
        "",
    ]
    for entry in flagged:
        lines.append(f"- [ ] **{entry['gene']}**: {entry['reason']}")
        lines.extend(f"  - {source}" for source in entry["evidence"])
    path.write_text("\n".join(lines) + "\n")
```

The link uses `https://biomni.phylo.bio`. If you're an Enterprise customer,
set `WEB_BASE` to your Biomni URL.

With Auto mode on, the task does not stop to wait for a person. Biomni answers
its own clarification questions and approves its own plan, and marks both in
the task.

![Gene list review task showing an auto-answered clarification and an auto-approved first-pass review plan](https://mintcdn.com/phylo/liKXOE1vbHNl7uvD/images/api-recipe-gene-review-auto-mode.png?fit=max\&auto=format\&n=liKXOE1vbHNl7uvD\&q=85\&s=361defb4c1ec1a746d6007e9d74ed399)

Auto mode in the review task: the clarification question was answered automatically and the plan was approved automatically.

## Run the script

Save the [full script](#full-script) as `gene_list_review.py` beside
`phylo_client.py`, then run:

```bash theme={null}
python gene_list_review.py
```

The script prints how many genes were flagged, and the paths to the checklist
and the task. Results are saved under `gene-review/<task-id>/`.

## Example results

The review found 10 genes plausible (NF1, MED12, NF2, CUL3, TADA2B, TADA1, CIC,
KEAP1, PTEN, DUSP4) and flagged 5:

| Gene | Why it was flagged |
| - | - |
| SEPT2 | Outdated symbol: the guide library must map it to SEPTIN2. |
| MARCH5 | Outdated symbol, and no established direction of effect on resistance. |
| OR4F5 | Not expressed in A375 or other melanoma lines; guides may also hit related olfactory receptors. |
| TTN | Only trace expression in A375, and below 1 TPM in every melanoma line measured. |
| LINC00473 | Noncoding RNA: there is no protein-coding frame to knock out. |

![Summary of the gene list review with 10 plausible genes and 5 flagged genes](https://mintcdn.com/phylo/liKXOE1vbHNl7uvD/images/api-recipe-gene-review-summary.png?fit=max\&auto=format\&n=liKXOE1vbHNl7uvD\&q=85\&s=493a99cd59a184f0fef32829098c5430)

The finished review: 10 genes plausible and 5 flagged, saved as review\.json.

Each checklist entry includes the agent's full reasoning and sources:

```markdown scientist_checklist.md theme={null}
# Gene list review: genes to check

Biomni's first-pass review: https://biomni.phylo.bio/projects/<project-id>/tasks/<task-id>
Reply in that task to ask Biomni follow-up questions about any gene.

- [ ] **SEPT2**: Not the current approved symbol: SEPT2 is a previous symbol of SEPTIN2 (HGNC:7729); ...
```

## Adapting this for your gene list

* Replace `GENES` with your list, and edit `REVIEW_PROMPT` to describe your
  screen and the checks you want.
* Keep a fixed verdict field, like `plausible` or `flag`, so your code can
  route results without reading the agent's prose.

## Full script

```python gene_list_review.py theme={null}
"""Gene list review: send a gene list for a first-pass review, then hand what
it flags to a scientist to check."""

import json
import os
from pathlib import Path

from phylo_client import PhyloClient

WEB_BASE = "https://biomni.phylo.bio"

# Top positively selected genes from a genome-wide CRISPR knockout screen for
# vemurafenib resistance in A375 melanoma cells.
GENES = [
    "NF1", "MED12", "NF2", "CUL3", "TADA2B", "TADA1", "CIC", "KEAP1",
    "SEPT2", "MARCH5", "OR4F5", "TTN", "PTEN", "DUSP4", "LINC00473",
]

REVIEW_PROMPT = """
These genes are the top hits from a genome-wide CRISPR knockout screen for
vemurafenib resistance in A375 BRAF V600E melanoma cells:

{genes}

Do a first-pass review of each gene before we spend bench time on it:
- Is the symbol current HGNC, and is it a protein-coding gene a CRISPR knockout
  can hit?
- Is it expressed in A375 or melanoma lines (DepMap/CCLE)?
- Is there published evidence linking its loss to BRAF or MAPK inhibitor
  resistance?
- Could it be a screen artifact (not expressed, very long gene, copy-number
  effect)?

Save raw JSON (no code fence) at /mnt/results/review.json, one entry per gene:
[{{"gene": "NF1", "verdict": "plausible" or "flag", "reason": "...",
   "evidence": ["PMID or source", "..."]}}]
""".strip()


def write_checklist(path, task_url, flagged):
    lines = [
        "# Gene list review: genes to check",
        "",
        f"Biomni's first-pass review: {task_url}",
        "Reply in that task to ask Biomni follow-up questions about any gene.",
        "",
    ]
    for entry in flagged:
        lines.append(f"- [ ] **{entry['gene']}**: {entry['reason']}")
        lines.extend(f"  - {source}" for source in entry["evidence"])
    path.write_text("\n".join(lines) + "\n")


def main():
    phylo = PhyloClient()
    project_id = (
        os.getenv("PHYLO_PROJECT_ID")
        or phylo.create_project(title="API demo")["id"]
    )

    task = phylo.create_task(
        project_id=project_id,
        title="Gene list review: vemurafenib resistance screen",
        initial_messages=[
            {"role": "user", "content": REVIEW_PROMPT.format(genes=", ".join(GENES))}
        ],
        auto_mode=True,
    )
    print(f"Review task: {task['id']}")
    phylo.wait_for_task(task["id"], poll_interval_seconds=60)

    results_dir = phylo.download_results(task["id"], Path("gene-review") / task["id"])
    review = json.loads((results_dir / "review.json").read_text())
    flagged = [entry for entry in review if entry["verdict"] == "flag"]

    task_url = f"{WEB_BASE}/projects/{project_id}/tasks/{task['id']}"
    checklist = results_dir / "scientist_checklist.md"
    write_checklist(checklist, task_url, flagged)
    print(f"{len(flagged)} of {len(review)} genes flagged for a scientist to check.")
    print(f"Checklist: {checklist}")
    print(f"Task: {task_url}")


if __name__ == "__main__":
    main()
```


# Running and grading an analysis
Source: https://docs.biomni.phylo.bio/api/recipes/running-an-analysis

Run an analysis task through the Phylo API, then grade its result in a second task

The Phylo API lets you run an analysis programmatically and check its result
automatically. This example runs an analysis based on BiomniBench-DA task
`da-18-7`, then starts a second Biomni task to grade the result. Both tasks run
on GPT 6 Astra (`model="custom:gpt-6-astra"`), the model we recommend for the
highest-quality analyses.

To make sure every task uses the model you chose, this recipe sets `disable_fallbacks`.

> [!NOTE]
>
> `custom:` models must be enabled for your workspace. If creating a task
> returns `403`, ask your Phylo representative to enable them, or set
> `model="max"` to run on the Max tier instead.

This recipe launches two Biomni tasks:

1. The first task runs the analysis
2. The second task grades the results of the first task

## Prerequisites

* [An API key](/api/authentication)
* Python 3.10 or later with the `requests` package

Install `requests`, then set your API key:

```bash theme={null}
python -m pip install requests
export PHYLO_API_KEY="<your-api-key>"
```

The script uses `https://api.phylo.bio/v1`. If you're an Enterprise customer,
set `PHYLO_BASE_URL` environment variable to the API base URL shared by your
Phylo representative.

## Run the analysis

**1. Set up a Python client**

For the purposes of this recipe, we'll use the Python client recipe.
Open [Building a Python client](/api/recipes/wrapping-the-api-in-python),
save the client as `phylo_client.py`, and place it in the directory where
you will run the analysis. The analysis script imports `PhyloClient` from
that file.

**2. Create the analysis script**

Save this script – which includes prompts for the analysis and grading – as `analysis.py` beside `phylo_client.py`:

```python analysis.py theme={null}
import json
import tarfile
from pathlib import Path

import requests

from phylo_client import PhyloClient

PROMPT = """
To identify genomic mechanisms driving endocrine resistance, determine whether
ESR1 mutations and MAPK pathway alterations are mutually exclusive or
co-occurring in post-hormonal therapy HR+/HER2- tumors.

The project contains three cBioPortal-format files from the public
BiomniBench-DA task da-18-7:

- data_clinical_sample.txt: Sample-level clinical annotations. Rows 1-4 are
  comment-prefixed metadata and the column header is on row 5.
- data_cna.txt: A gene-by-sample discrete copy-number alteration matrix, where
  -2 is deep deletion and 2 is amplification.
- data_mutations.txt: A Mutation Annotation Format table with gene, sample,
  protein-change, variant-classification, and read-count fields.

Analyze the project files directly. Document the cohort selection, alteration
definitions, statistical method, quantitative results, biological
interpretation, and limitations.

Save these two files under /mnt/results/:

1. trace.md with sections named Objective, Data Sources, Approach, Results, and
   References. Include the actual analysis code, rationale for analytical
   choices, and quantitative intermediate results.
2. answer.txt with a concise plain-text answer to the research question.

The files come from the MSK-IMPACT cohort associated with "Genomic Landscape of
Endocrine-Resistant Advanced Breast Cancers." Do not search for or read that
paper, its figures, or its supplementary material. Solve the task from the
project files and domain knowledge.
""".strip()

JUDGE_PROMPT = """
Score the BiomniBench-DA task da-18-7 response in the project files trace.md
and answer.txt. Judge only the evidence in those two files. Do not redo the
analysis, inspect another project's files, or use external sources.

Choose exactly one listed level for each criterion. Do not award partial points
between levels.

1. Cohort Selection (15 points)
   A, 15: Restricts the analysis to hormone receptor-positive, HER2-negative
   tumors collected after hormonal therapy and explains the selection.
   B, 7: Uses the correct receptor subtype but mixes primary and metastatic
   samples or mislabels some samples.
   C, 0: Does not restrict the analysis to the specified cohort.

2. ESR1 Ligand-Binding Domain Mutations (20 points)
   A, 20: Defines ESR1 LBD mutations as nonsynonymous variants within amino
   acids 300-550 and correctly identifies them in the data.
   B, 10: Identifies ESR1 mutations but does not restrict them to the LBD or
   misclassifies some variants.
   C, 0: Does not properly identify ESR1 LBD mutations.

3. MAPK Pathway Alterations (20 points)
   A, 20: Defines MAPK alterations as nonsynonymous mutations in ERBB2, NF1,
   EGFR, KRAS, HRAS, BRAF, and MAP2K1, plus NF1 deletions and EGFR
   amplifications, and correctly calls them.
   B, 10: Omits specified genes, copy-number events, or other required details.
   C, 0: Uses an incorrect gene set or misidentifies alterations.

4. Statistical Testing (20 points)
   A, 20: Constructs a 2-by-2 table of ESR1 LBD mutation status versus MAPK
   alteration status and performs a one-sided Fisher exact test for mutual
   exclusivity, reporting the p-value.
   B, 10: Constructs the table but uses an inappropriate test or does not state
   the direction.
   C, 0: Does not perform statistical testing.

5. Results Reporting (15 points)
   A, 15: Reports counts for ESR1 LBD only, MAPK only, both, and neither; gives
   the Fisher test p-value; and states whether co-occurrence is rare.
   B, 7: Reports some counts but omits the contingency table or p-value.
   C, 0: Does not report the required results.

6. Interpretation and Biological Context (10 points)
   A, 10: Interprets the result as evidence that ESR1 LBD mutations and MAPK
   alterations are largely mutually exclusive endocrine-resistance mechanisms
   and discusses therapeutic implications.
   B, 5: Interprets the result but omits biological context or therapeutic
   relevance.
   C, 0: Provides no interpretation or an incorrect conclusion.

7. Source Reliability (0 points, with penalties)
   A, 0: Values and identifiers are traceable to the project files or documented
   transformations, methods match the analysis, and external claims use
   identifiable references.
   B, -5: Most evidence is traceable, but some claims lack clear attribution.
   C, -10: Values, identifiers, or claims lack a clear source or are fabricated.

Save the result as raw JSON at /mnt/results/score.json using this shape:
{
  "source_task": "da-18-7",
  "total_score": 0,
  "criteria": [
    {
      "criterion": "Cohort Selection",
      "level": "A",
      "points": 15,
      "max_points": 15,
      "reason": "Evidence-based explanation"
    }
  ],
  "summary": "Concise overall assessment"
}

Include all seven criteria. Set total_score to the point sum clamped to the
0-100 range. Do not wrap the JSON in a Markdown code fence.
""".strip()


def stage_input_files():
    archive_url = (
        "https://datahub.assets.cbioportal.org/breast_msk_2018.tar.gz"
    )
    archive_path = Path("breast_msk_2018.tar.gz")
    filenames = (
        "data_clinical_sample.txt",
        "data_cna.txt",
        "data_mutations.txt",
    )
    timeout_seconds = 60

    response = requests.get(archive_url, timeout=timeout_seconds)
    response.raise_for_status()
    archive_path.write_bytes(response.content)

    paths = []
    with tarfile.open(archive_path) as archive:
        for filename in filenames:
            path = Path(filename)
            source = archive.extractfile(f"breast_msk_2018/{filename}")
            path.write_bytes(source.read())
            paths.append(path)
            print(f"Staged: {path}")
    return paths


def run_analysis_task(phylo, input_paths):
    # Call the Phylo API to create a project for the analysis.
    project = phylo.create_project(
        title="Breast-cancer endocrine resistance analysis",
        description="ESR1 and MAPK alteration mutual exclusivity",
    )
    project_id = project["id"]
    print(f"Created project: {project_id}")

    for input_path in input_paths:
        # Call the Phylo API to upload each input file to the project.
        phylo.upload_file(project_id, input_path)
        print(f"Uploaded: {input_path.name}")

    # Call the Phylo API to create and start the analysis task.
    task = phylo.create_task(
        project_id=project_id,
        title="BiomniBench-DA task da-18-7",
        initial_messages=[{"role": "user", "content": PROMPT}],
        model="custom:gpt-6-astra",
        disable_fallbacks=True,
        auto_mode=True,
    )
    task_id = task["id"]
    print(f"Started task: {task_id}")

    # Poll the Phylo API until the analysis task finishes.
    phylo.wait_for_task(task_id)

    # Call the Phylo API to download the analysis task's result files.
    output_directory = phylo.download_results(
        task_id,
        Path("analysis-results") / task_id,
    )
    print(f"Analysis results: {output_directory}")

    # Call the Phylo API to save the full agent trace beside the results.
    trace_path = output_directory / "messages.json"
    trace_path.write_text(json.dumps(phylo.get_all_messages(task_id), indent=2))
    print(f"Analysis trace: {trace_path}")
    return task_id, output_directory


def score_results_with_llm_judge(phylo, analysis_task_id, output_directory):
    # Call the Phylo API to create an isolated project for the judge.
    judge_project = phylo.create_project(
        title="Breast-cancer endocrine resistance analysis judge",
    )
    judge_project_id = judge_project["id"]
    print(f"Created judge project: {judge_project_id}")

    for filename in ("trace.md", "answer.txt"):
        # Call the Phylo API to upload each candidate result for judging.
        phylo.upload_file(judge_project_id, output_directory / filename)

    # Call the Phylo API to create and start the judge task.
    judge_task = phylo.create_task(
        project_id=judge_project_id,
        title=f"Score BiomniBench-DA task da-18-7 run {analysis_task_id}",
        initial_messages=[{"role": "user", "content": JUDGE_PROMPT}],
        model="custom:gpt-6-astra",
        disable_fallbacks=True,
        auto_mode=True,
    )
    judge_task_id = judge_task["id"]
    print(f"Started judge task: {judge_task_id}")

    # Poll the Phylo API until the judge task finishes.
    phylo.wait_for_task(judge_task_id)

    # Call the Phylo API to download the judge task's result files.
    judge_output_directory = phylo.download_results(
        judge_task_id,
        output_directory / "judge",
    )
    score_path = judge_output_directory / "score.json"
    score = json.loads(score_path.read_text())
    print(f"Judge score: {score['total_score']}/100")
    print(f"Judge details: {score_path}")


def main():
    phylo = PhyloClient()
    input_paths = stage_input_files()
    task_id, output_directory = run_analysis_task(phylo, input_paths)
    score_results_with_llm_judge(phylo, task_id, output_directory)


if __name__ == "__main__":
    main()
```

**3. Run the script**

Run the analysis from the directory containing both Python files:

```bash theme={null}
python analysis.py
```

The script downloads the public cBioPortal study archive, then stages and
uploads three input files totaling about 4.8 MB. The first task runs the
analysis, and the second task grades its results. Analysis output is saved
under `analysis-results/<task-id>/`, along with the full
agent trace as `messages.json`; judge output is saved in its `judge/`
subdirectory.

## Adapting this for your analysis

To adapt this to your analysis, you can either:

1. Replace `PROMPT` and `JUDGE_PROMPT` with your analysis prompt and rubric.
2. Use this as a base for a [batch analysis across many datasets](/api/recipes/batch-analysis).

If you choose to launch multiple tasks at once, you may hit the limits
for your account. These will be reflected as `429` errors from either the Phylo
API or internal tools used by the Biomni agent, such as tasks spawned on the
HPC. If you encounter these errors, limit the number of tasks you start with
the Phylo API.


# Building a Python client
Source: https://docs.biomni.phylo.bio/api/recipes/wrapping-the-api-in-python

Until we have an official Python SDK, if you'd like to use a Python library
rather than interacting directly with the API, you can use this recipe for a
basic Python SDK for the Phylo API.

## Prerequisites

* [An API key](/api/authentication)
* Python 3.10 or later with the `requests` package

Install `requests`, then set your API key:

```bash theme={null}
python -m pip install requests
export PHYLO_API_KEY="<your-api-key>"
```

To use another API base URL, set the `PHYLO_BASE_URL` environment variable.

## Functions in this recipe

* `create_project()`: Creates a project.
* `list_projects()`: Lists projects in the API key's workspace.
* `create_task()`: Creates a task in `max` and Auto mode by default, with
  optional initial messages.
* `upload_file()`: Uploads files.
* `send_message()`: Sends a message and optional file attachments to a task.
* `get_task()`: Gets the current task status and metadata.
* `wait_for_task()`: Polls until a task completes, fails, or is cancelled.
* `get_all_messages()`: Fetches every message in a task, including the agent's
  tool calls and results.
* `download_results()`: Downloads every result file from a completed task.

## Create the client

Copy this file and save it as `phylo_client.py`:

```python phylo_client.py theme={null}
import json
import mimetypes
import os
import time
from pathlib import Path, PurePosixPath

import requests


PHYLO_BASE_URL = os.getenv("PHYLO_BASE_URL", "https://api.phylo.bio/v1")
REQUEST_TIMEOUT_SECONDS = 60
POLL_INTERVAL_SECONDS = 15
TASK_TIMEOUT_SECONDS = 24 * 60 * 60
TERMINAL_TASK_STATUSES = {"completed", "failed", "cancelled"}
MESSAGE_PAGE_LIMIT = 500
MAX_MESSAGE_PAGES = 1000


class PhyloClient:
    def __init__(self, api_key=None, api_base=None):
        self.api_base = (api_base or PHYLO_BASE_URL).rstrip("/")
        self.session = requests.Session()
        self.session.headers["Authorization"] = (
            f"Bearer {api_key or os.environ['PHYLO_API_KEY']}"
        )

    def _request(self, method, path, **kwargs):
        response = self.session.request(
            method,
            f"{self.api_base}{path}",
            timeout=REQUEST_TIMEOUT_SECONDS,
            **kwargs,
        )
        response.raise_for_status()
        return response.json() if response.content else {}

    def list_projects(self):
        return self._request("GET", "/projects")

    def create_project(self, title, description=None):
        body = {"title": title}
        if description is not None:
            body["description"] = description
        return self._request("POST", "/projects", json=body)

    def create_task(
        self,
        project_id,
        title=None,
        initial_messages=None,
        model="max",
        auto_mode=True,
        disable_fallbacks=False,
    ):
        body = {
            "project_id": project_id,
            "auto_mode": auto_mode,
            "disable_fallbacks": disable_fallbacks,
        }
        if title is not None:
            body["title"] = title
        if initial_messages is not None:
            body["initial_messages"] = initial_messages
        if model is not None:
            body["model"] = model
        return self._request("POST", "/experimental/tasks", json=body)

    def upload_file(self, project_id, path, mime_type=None):
        path = Path(path)
        mime_type = (
            mime_type
            or mimetypes.guess_type(path.name)[0]
            or "application/octet-stream"
        )
        intent = self._request(
            "POST",
            "/experimental/files",
            json={
                "project_id": project_id,
                "filename": path.name,
                "size_bytes": path.stat().st_size,
                "mime_type": mime_type,
            },
        )
        if intent["upload_type"] != "single":
            raise RuntimeError("This client only handles single-part uploads.")

        with path.open("rb") as file_handle:
            upload = requests.post(
                intent["upload_url"],
                data=intent["fields"],
                files={"file": (path.name, file_handle, mime_type)},
                timeout=REQUEST_TIMEOUT_SECONDS,
            )
        upload.raise_for_status()

        self._request(
            "POST",
            f"/experimental/files/{intent['file_id']}/finalize",
            json={},
        )
        return intent["file_id"]

    def send_message(self, task_id, content, file_ids=None):
        return self._request(
            "POST",
            f"/experimental/tasks/{task_id}/messages",
            json={"content": content, "file_ids": file_ids or []},
        )

    def get_task(self, task_id):
        return self._request("GET", f"/experimental/tasks/{task_id}")

    def wait_for_task(
        self,
        task_id,
        timeout_seconds=TASK_TIMEOUT_SECONDS,
        poll_interval_seconds=POLL_INTERVAL_SECONDS,
    ):
        deadline = time.monotonic() + timeout_seconds
        while time.monotonic() < deadline:
            task = self.get_task(task_id)
            status = task["status"]
            print(f"Task status: {status}")
            if status in TERMINAL_TASK_STATUSES:
                if status != "completed":
                    raise RuntimeError(f"Task ended with status: {status}")
                return task
            time.sleep(poll_interval_seconds)
        raise TimeoutError(f"Task did not finish within {timeout_seconds} seconds")

    def get_all_messages(
        self,
        task_id,
        page_limit=MESSAGE_PAGE_LIMIT,
        max_pages=MAX_MESSAGE_PAGES,
    ):
        messages = []
        before_id = None
        for _ in range(max_pages):
            params = {"limit": page_limit}
            if before_id is not None:
                params["before_id"] = before_id
            page = self._request(
                "GET",
                f"/experimental/tasks/{task_id}/messages",
                params=params,
            )
            messages = page["data"] + messages
            if not page["has_more"]:
                return messages
            before_id = page["first_id"]
        raise RuntimeError(f"Task has more than {max_pages} pages of messages.")

    def download_results(self, task_id, output_directory):
        output_directory = Path(output_directory).resolve()
        output_directory.mkdir(parents=True, exist_ok=True)

        after_id = None
        downloaded_count = 0
        while True:
            params = {"with_urls": "true"}
            if after_id is not None:
                params["after_id"] = after_id
            page = self._request(
                "GET",
                f"/experimental/tasks/{task_id}/results",
                params=params,
            )

            for result in page["data"]:
                name = result["name"]
                relative_path = PurePosixPath(name)
                if (
                    not relative_path.parts
                    or relative_path.is_absolute()
                    or ".." in relative_path.parts
                    or "\\" in name
                ):
                    raise ValueError(f"Unsafe result path: {name}")

                output_path = output_directory.joinpath(*relative_path.parts)
                output_path.parent.mkdir(parents=True, exist_ok=True)
                if output_directory not in output_path.resolve().parents:
                    raise ValueError(f"Unsafe result path: {name}")
                if output_path.exists():
                    raise FileExistsError(f"Result path already exists: {output_path}")

                response = requests.get(
                    result["download_url"],
                    timeout=REQUEST_TIMEOUT_SECONDS,
                )
                response.raise_for_status()
                output_path.write_bytes(response.content)
                downloaded_count += 1
                print(f"Downloaded: {output_path}")

            if not page["has_more"]:
                break
            after_id = page["last_id"]

        if downloaded_count == 0:
            raise RuntimeError("The task completed without result files.")

        return output_directory


if __name__ == "__main__":
    print(json.dumps(PhyloClient().list_projects(), indent=2))
```

Run it to verify your API key by listing your projects:

```bash theme={null}
python phylo_client.py
```

To import it, place `phylo_client.py` beside your script:

```python theme={null}
# some-directory/
# ├── phylo_client.py
# └── analysis.py  # The file where you're importing phylo_client

from phylo_client import PhyloClient

phylo = PhyloClient()
project = phylo.create_project(title="My API project")
print(project["id"])
```


# FAQ
Source: https://docs.biomni.phylo.bio/faq

Frequently asked questions about Biomni Lab

Find answers to common questions about using Biomni Lab.

## General

> [accordion] What is Biomni Lab?
>
> Biomni Lab is an AI-powered research assistant designed for biomedical and life sciences research. It combines large language models with specialized bioinformatics tools, databases, and computational resources to help you analyze data and accelerate your research.

> [accordion] Do I need bioinformatics experience to use Biomni Lab?
>
> No. Biomni Lab is designed to be accessible to researchers at all skill levels. You can describe what you want to accomplish in plain language, and Biomni Lab will handle the technical details. However, having domain knowledge about your research area helps you ask better questions and interpret results.

> [accordion] What types of research does Biomni Lab support?
>
> Biomni Lab specializes in biomedical and life sciences research, including:
>
> * Genomics and transcriptomics
> * Proteomics and structural biology
> * Single-cell analysis
> * Pathway and network analysis
> * Biostatistics and machine learning
> * Literature and database searches

## Trust & Accuracy

> [accordion] Is my data secure?
>
> Yes. We do not share your data with other users. See our privacy policy for details.

> [accordion] Can I trust Biomni Lab's results? How do you prevent AI hallucinations?
>
> Biomni Lab is built with multiple safeguards to ensure accurate, reliable results:
>
> **Citations & References**
>
> * All database queries link directly to source records (UniProt, NCBI, PDB, etc.)
> * Literature references include DOIs and links to published papers
> * Tool parameters and methods are documented with official references
>
> **Review Mode**
>
> * Click the **Review** button at the top of any session to verify results
> * See all claims with their supporting evidence
> * Check data sources and identify assumptions
>
> **Hallucination Guardrails**
>
> * Claims are cross-referenced against authoritative databases
> * Uncertain results are flagged with confidence indicators
> * Input/output data is validated against expected formats
> * All steps are logged for reproducibility
>
> While these measures significantly reduce errors, we recommend verifying critical findings through independent sources—especially for clinical applications or publication-ready research.

> [accordion] How do I verify Biomni Lab's results?
>
> Use the **Review** button at the top of any session to enter review mode. This shows:
>
> * All claims and statements with supporting evidence
> * Direct links to database records and literature
> * Data sources used in the analysis
> * Any assumptions or caveats
>
> You can also ask Biomni Lab to explain its reasoning or provide additional citations for any claim.

## Files & Data

> [accordion] What file formats does Biomni Lab support?
>
> Biomni Lab supports common bioinformatics formats including:
>
> * **Sequences**: FASTA, FASTQ, FASTQ.GZ
> * **Alignments**: SAM, BAM, CRAM
> * **Variants**: VCF, BCF, GVCF
> * **Tabular**: CSV, TSV, XLSX, TXT
> * **Annotations**: GFF, GTF, BED
> * **Images**: PNG, JPG, SVG, PDF

> [accordion] What is the maximum file size I can upload?
>
> The maximum file size is 10 GB per file. Contact support if you need to process larger files.

> [accordion] How long are my files stored?
>
> Files are stored for the duration of your account and can be downloaded or deleted at any time.

> [accordion] Can I upload compressed files?
>
> Yes. Biomni Lab supports gzip-compressed files (.gz) for sequences and other large files. This is recommended for FASTQ files to save upload time and storage space.

## Analysis & Tools

> [accordion] What bioinformatics tools are available?
>
> Biomni Lab has access to many popular tools including:
>
> * **Alignment**: Bowtie2, BWA, STAR, HISAT2
> * **Variant calling**: GATK, BCFtools, FreeBayes
> * **RNA-seq**: DESeq2, edgeR, featureCounts
> * **Single-cell**: Seurat, Scanpy
> * **Structure**: AlphaFold
> * **Visualization**: ggplot2, matplotlib, seaborn
>
> See the [Resources](/features/resources) page for a complete list.

> [accordion] How long do analyses take?
>
> Analysis time varies depending on:
>
> * Data size and complexity
> * Tools being used
> * Current system load
>
> Simple queries complete in seconds. Alignment of a typical RNA-seq sample takes 10-30 minutes. Large genome analyses may take several hours. Biomni Lab shows progress updates during long-running tasks.

> [accordion] Can I run custom scripts?
>
> Biomni Lab can write and execute Python and R code for your analyses. If you have specific requirements, you can ask Biomni Lab to implement custom analysis pipelines. However, you cannot upload and run arbitrary executable files for security reasons.

## Compute & Limits

> [accordion] What are the compute resources available?
>
> Each analysis session has access to:
>
> * **CPU**: Multi-core processing for parallel computations
> * **Memory**: Sufficient RAM for most bioinformatics workflows
> * **GPU**: Available for specific tools (marked with HPC badge) like AlphaFold and deep learning models
> * **Storage**: Temporary workspace for intermediate files during analysis
>
> Pro users get higher resource limits across the board. See the [Pricing FAQ](/pricing-faq) for details.

> [accordion] Are there limits on how many analyses I can run?
>
> Yes. Usage is tracked based on the underlying LLM and compute resources consumed — not a simple message count. Each plan has a daily usage allowance that resets every day, and Pro users get 10x the daily allowance of Free users. You can also run multiple sessions concurrently (Free: up to 5, Pro: up to 10). You can check your current usage on the [Settings](https://biomni.phylo.bio/settings) page.

> [accordion] What happens if I hit a limit?
>
> * **Daily usage limit**: Your tasks are queued until your usage resets the next day. See the [Pricing FAQ](/pricing-faq) for more details.
> * **File size limit**: Upload will fail with an error message. Try compressing the file or contact support.
> * **Storage limit**: You'll need to delete files before uploading more. Download important results first.

## Projects & Organization

> [accordion] What's the difference between a Quick Task and a Project?
>
> * **Quick Task**: A standalone analysis session for one-off questions or explorations. Good for trying things out.
> * **Project**: An organized workspace for related analyses. Projects help you keep files, tasks, and results organized for ongoing research.

> [accordion] Can I give a project its own context, instructions, or skills?
>
> Yes. Go to [Settings](https://biomni.phylo.bio/settings) → Projects and pick a project. You can set:
>
> * **Project context** — what the agent should know before starting any task here, such as the organism, assay, or dataset you work with
> * **Custom instructions** — how the agent should respond in this project, for example always showing the code it ran
> * **Auto attached skills** — skills added to the first message of every new task in the project
>
> These apply to tasks created from then on. Anyone can still attach other skills task by task.

> [accordion] How many skills should I attach to a project?
>
> As few as you genuinely need every time. Every auto attached skill is read at the start of every task in the project, even when that task does not use it — taking up context and increasing the odds the agent follows the wrong instruction. Attach the rest task by task instead.

> [accordion] Can I collaborate with my team?
>
> Yes. You can invite team members to your organization and share projects with them. Team members can view and contribute to shared projects while keeping personal work private.

> [accordion] Can I export my results?
>
> Yes. All results can be downloaded including:
>
> * Generated files (BAM, VCF, CSV, etc.)
> * Figures and visualizations
> * Analysis reports
> * Chat transcripts

## Account & Billing

For detailed pricing, plan comparisons, academic discounts, and billing questions, see the **[Pricing FAQ](/pricing-faq)**.

> [accordion] How do I delete my account?
>
> Contact [support@phylo.bio](mailto:support@phylo.bio) to manage your account. Your data will be retained for 30 days after cancellation.

## Troubleshooting

> [accordion] My analysis is taking too long. What should I do?
>
> * Check that your input files are in the correct format
> * For large files, ensure they're compressed (.gz)
> * Consider breaking the analysis into smaller batches
> * Contact support if an analysis seems stuck

> [accordion] Biomni Lab doesn't understand my request. How can I improve it?
>
> * Be more specific about what you want to accomplish
> * Mention your input files using @ references
> * Specify the tools or methods you want to use
> * Break complex requests into smaller steps
> * See [How to Prompt](/how-to-prompt) for detailed tips

> [accordion] I got an error. What should I do?
>
> * Check the error message for specific issues (wrong file format, missing data, etc.)
> * Try rephrasing your request with more details
> * If the error persists, report it using the bug icon in the top-right corner
> * Check the [Bug Reporting](/support/bug-reporting) page for more information

> [accordion] My file upload failed. What went wrong?
>
> Common causes:
>
> * File exceeds size limit
> * Unsupported file format
> * Network interruption
> * File is corrupted
>
> Try compressing large files, checking the format, and ensuring a stable connection.

## Still Have Questions?

* **[Join our Slack](https://join.slack.com/t/biomnigroup/shared_invite/zt-478z7aarm-~JC0jFpGZZorug6FhcuZFA)** - Chat with the community and Biomni Lab team
* **[Contact Support](/support/customer-support)** - Get help from our support team
* **[Report a Bug](/support/bug-reporting)** - Let us know if something isn't working


# Chemical Structures
Source: https://docs.biomni.phylo.bio/features/chemical-structures

Preview, draw, and edit small molecules

Biomni draws 2D structures for molecule files and lets you draw molecules to
send to a task or add to a result file.

## Preview molecule files

Open a supported file to see its structures:

* **SDF** files open as a **2D table**, a **2D grid**, or a **3D structure**.
* **CSV**, **TSV**, and **SMI** files draw SMILES columns in place. Biomni
  detects structure columns, and you can choose which columns are drawn.

Large libraries are split into pages.

## Draw a molecule for a message

1. Select **+ Add** in the composer.
2. Choose **Draw molecule**.
3. Draw the structure and select **Add**.

The drawing is saved as a SMILES (`.smi`) file in the project's
`drawn-molecules-input` folder and attached to your message. Add one molecule
at a time.

## Edit molecules in a result file

SDF, CSV, TSV, and SMI files generated by a task can be edited from their
preview:

* **Add molecule** appends a new structure to the end of the file. Only the
  structure is added; other columns stay empty.
* **Edit molecule** (the pencil on a structure in the table, or the tile menu
  in the grid) opens the structure in the editor:
  * **Save changes** replaces the structure. Other values in that row are left
    out unless you tick them under **Keep values**, because they may not
    describe the new structure.
  * **Add as new molecule** appends the edited structure and leaves the
    original unchanged.
* **Delete** in the row or tile menu removes that molecule.

Saving changes and deleting both show an **Undo** option.

> [!NOTE]
>
> Editing is available for task result files up to 25 MB, once the agent has
> finished. A file must keep at least one molecule. Files in shared replays and
> project files outside a task's results can be previewed but not edited.
> Drawing and editing molecules may not be enabled in every workspace.

For other file actions, see [Projects & Drive](/features/projects-and-drive).


# Cloud Storage
Source: https://docs.biomni.phylo.bio/features/cloud-storage

Bring files into a project from connected drives or public links

Cloud imports copy selected external files into the current project. Available
sources depend on your plan and workspace.

## Import files into a project

From a task:

1. Select **+ Add** in the composer.
2. Choose **Import from cloud storage**.
3. Connect a provider, paste a supported public link, or select an available
   source.
4. Choose the files or folders to import.
5. Wait for the import to finish before asking Biomni to use the files.

Imported files are copied into Biomni-managed project storage. They then behave
like other project files: authorized project members can browse, preview,
download, and attach them according to their project role.

Cloud imports support provider connections and selected public links, including
Google Drive, Dropbox, and S3 sources. The exact choices shown in the dialog can
vary by workspace.

> [!NOTE]
>
> A cloud import is a copy. Updating the source file later does not automatically
> update the imported project file.

## Choose the right option

| Goal | Use |
| - | - |
| Work on a stable copy inside a project | Cloud import |
| Attach a local file or folder | Upload files / Upload folder |
| Keep generated output with the task | Results |

For project file organization, see [Projects & Drive](/features/projects-and-drive).


# Collaboration
Source: https://docs.biomni.phylo.bio/features/collaboration

Share projects with members of your Team workspace

Team workspaces can share a project with selected active members or with the
whole workspace. Personal workspaces remain private.

Project sharing includes the project's tasks, files, results, notes, Drive
content, and other project-owned resources. Access is checked against current
workspace membership.

> [!NOTE]
>
> Chat access handoff is available to everyone and is labeled **Beta** in the app.

## Access levels

| Role | What it allows |
| - | - |
| **Viewer** | Read tasks, files, notes, and results |
| **Editor** | Create tasks, continue chats handed to them, upload files, and change project content |
| **Admin** | Manage access and project settings, and delete the project when deletion requirements are met |

Every task has one person with chat access who can send messages and control it.
That person can hand off chat access to an active project Editor or Admin after
the current response finishes when the task belongs to a shared project. The
**Transfer** button is in the task header next to Share; for unshared projects it is
disabled and explains that only sessions in shared projects can be transferred.
The previous participant immediately becomes read-only. Project Admins can
reassign chat access if the current participant is no longer available.
Session notes and creator attribution remain with the original task creator.

## Share a project

If you are a project Admin:

1. Select **Share** next to the project name in the project sidebar.
2. Add a workspace member and choose Viewer, Editor, or Admin.
3. Save the changes.

You can also grant the entire workspace Viewer or Editor access. Workspace
admins can turn this off with **Allow members to share projects with the entire
workspace** in **Settings → Permissions**.
Admin access must be assigned to an individual member.

## Working in a shared project

* Tasks display their creator and the participant with chat access.
* The current participant can use **Transfer** to let one Editor or Admin
  continue the conversation. Multiple members cannot send messages at the same
  time.
* Project files and results inherit the project's access level.
* Viewers can open and download accessible files but cannot start compute or
  change project content.
* Editors can create their own tasks and add files, but cannot change sharing or
  project-wide instructions.
* Project context, custom instructions, and auto attached Skills are visible to
  members; only Admins can edit them.

> [!WARNING]
>
> Removing a member's project access stops future access but does not delete work
> they created. Project deletion is blocked while other members still own project
> tasks/files or while compute and billing activity is unsettled.

For project structure and settings, see
[Projects & Drive](/features/projects-and-drive).


# MCP Connectors
Source: https://docs.biomni.phylo.bio/features/connectors

Connect external tools and services so the agent can use them in your tasks

MCP connectors let Biomni Lab work with approved external tools and services directly inside a task. Once you connect an account, the agent can call that service's tools on your behalf: opening issues, reading pull requests, updating projects, and more.

Model Context Protocol (MCP) is an open standard for connecting AI agents to external tools. Any compatible service that your organization makes available can be connected to Biomni Lab.

> [!NOTE]
>
> Connectors are set up per person. Connecting an account only lets the agent see what that account can already see—and only while it is working on a task you started.

## Available connectors

Your organization chooses which connectors are available. Open **Settings → Connectors** to see the current catalog for your workspace.

Organization admins can also add **custom connectors** for compatible MCP servers—see [For organization admins](#for-organization-admins).

> [!NOTE]
>
> If you don't see any connectors under **Settings → Connectors**, an organization admin may need to enable one first. Feature availability and the built-in connector catalog vary by workspace.

## Connecting a connector

1. Open **Settings → Connectors**.
2. Find the connector under **MCP Connectors** and click **Connect**.
3. Complete sign-in using one of the methods below.

> [tab] OAuth
>
> A popup opens to the service's sign-in page. Approve access, and the popup closes automatically. The row updates to show a **Connected** badge and the account you linked.
>
> ![Settings Connectors panel showing the MCP Connectors card with GitHub in the Connected state](https://mintcdn.com/phylo/qgDLbyvgnfIr4cVG/images/connectors-connect.png?fit=max\&auto=format\&n=qgDLbyvgnfIr4cVG\&q=85\&s=1ad2e60cc4d3d29d155b4285f3499d0b)
>
> > [!NOTE]
> >
> > If nothing happens when you click **Connect**, your browser may have blocked the popup. Allow popups for this site, then try connecting again.

> [tab] Personal access token
>
> Some custom connectors ask for a token instead of a popup. Paste a personal access token for the service and click **Connect**. Your token is stored encrypted and used only to call that server's tools on your behalf.
>
> ![Connect dialog with a Personal access token field](https://mintcdn.com/phylo/qgDLbyvgnfIr4cVG/images/connectors-pat-dialog.png?fit=max\&auto=format\&n=qgDLbyvgnfIr4cVG\&q=85\&s=1ec340832dd1b3d7b3f9e45d5d95bc3e)

## Using connector tools in a task

Once connected, just describe what you want—the agent picks the right tool automatically. You don't need to `@` mention anything.

```text theme={null}
Open a GitHub issue in acme/genome-pipeline titled "Add a QC step"
and summarize the three most recent open issues.
```

The agent only uses connectors you've connected, and only the tools you've left enabled.

## Choosing which tools the agent can use

Each connected server exposes a set of tools. Expand **Tools** on a connected row to see them, grouped into **Read-only** and **Write**. Every tool has a switch—toggle one off to stop the agent from using it.

![Expanded Tools panel with per-tool switches and a Refresh button](https://mintcdn.com/phylo/qgDLbyvgnfIr4cVG/images/connectors-tools.png?fit=max\&auto=format\&n=qgDLbyvgnfIr4cVG\&q=85\&s=f16f8dde68467cdd3047eff1557c9e40)

> [!TIP]
>
> Want the agent to look but not touch? Turn off the **Write** tools and leave **Read-only** on. State the same restriction in your request.

Click **Refresh** to re-fetch the tool list if the server has changed.

## Disconnecting

Click **Disconnect** on a connected row to remove your account and stop the agent from using that server. You can reconnect anytime.

## For organization admins

Admins and owners control which connectors the whole organization can use.

> [!NOTE]
>
> Manage the workspace connector catalog under **Settings → Connectors**.

### Enabling a connector

Toggle a connector's switch on to make it available to your members. They'll then see it under **Settings → Connectors** and can connect their own accounts. Toggle it off to hide it again.

![Admin connector list with enable switches and an Add custom connector button](https://mintcdn.com/phylo/qgDLbyvgnfIr4cVG/images/connectors-admin.png?fit=max\&auto=format\&n=qgDLbyvgnfIr4cVG\&q=85\&s=ef83a4d2498b6dd3e9c900821c2880ae)

### Adding a custom connector

Connect any MCP server your team runs or subscribes to:

1. Click **Add custom connector**.
2. Fill in the details:
   * **Name** — how the connector appears to members (e.g. *My Company API*)
   * **Server URL** — the server's MCP endpoint (e.g. `https://mcp.example.com/mcp`)
   * **Authentication** — how members sign in:
     * **OAuth (dynamic registration)** — members sign in through the server's OAuth flow
     * **Personal access token** — each member pastes their own token
   * **Description** *(optional)*
3. Click **Add connector**.

![Add a custom MCP server dialog with Name, Server URL, and Authentication fields](https://mintcdn.com/phylo/qgDLbyvgnfIr4cVG/images/connectors-add-custom.png?fit=max\&auto=format\&n=qgDLbyvgnfIr4cVG\&q=85\&s=59d505662558c319dfbf419221c93262)

The connector appears in the list with a **Custom** badge, ready for members to connect.

### Removing a custom connector

Click the delete icon on a custom connector and confirm. Built-in connectors can't be deleted—only disabled.

> [!WARNING]
>
> Deleting a custom connector removes it for the whole organization and disconnects every member's connection to it. This can't be undone.

## Security & privacy

* **Per-person connections.** Connecting is per user; the agent only ever acts with your own access.
* **Encrypted at rest.** OAuth tokens and personal access tokens are stored encrypted.
* **Used only during your tasks.** The agent calls connector tools on your behalf while working on a task you started.
* **You stay in control.** Disable individual tools or disconnect at any time. Admins control which connectors exist for the organization.

Never paste an external-service credential into a task message or personal instruction. Enter it only in the connector's credential flow.


# Personalization & Memory
Source: https://docs.biomni.phylo.bio/features/memory

Set persistent preferences and project-specific instructions

Biomni uses conversation context, personal instructions, and project settings at
different scopes. Choose the narrowest scope that fits the instruction.

## Conversation context

Within a task, Biomni can use earlier messages, attached files, and generated
results. Keep follow-up refinements in the same task:

```text theme={null}
Use the same filtered cohort, but stratify the result by treatment arm.
```

Start a new task when the goal or evidence boundary changes substantially.

## Personal instructions

Open **Settings → Personalization** and add entries under **Custom
Instructions**. Add durable preferences such as:

* preferred programming language;
* desired figure or report format;
* terminology and units to use; or
* response conventions you want across tasks.

Personal instructions are stored for your user in the active workspace and are
included when Biomni starts work. You can edit or remove them at any time.

> [!TIP]
>
> Write preferences as direct instructions: “Use R for statistical analysis” is
> clearer than “I sometimes prefer R.”

## Project settings

Use **Settings → Projects** for context or instructions that apply only to one
project. Project settings include:

* project context;
* ordered custom instructions; and
* auto attached Skills for the first message of new tasks.

Project instructions are more specific than personal instructions. Changes are
captured by new tasks and do not rewrite existing conversations.

## What not to store

Do not put passwords, API keys, access tokens, private keys, or other credentials
in personal or project instructions. Use approved connection and secret-management
flows instead.

For project-level configuration, see
[Projects & Drive](/features/projects-and-drive).


# Models & Compute
Source: https://docs.biomni.phylo.bio/features/models-and-compute

Choose a model profile and understand how Biomni runs computational work

Biomni separates the model that plans and reasons from the compute that runs
code, scientific tools, and larger pipelines.

## Model profiles

When the model selector is available, choose a profile from the composer:

| Profile | Best for | Usage |
| - | - | - |
| **Standard** | Everyday research and analysis | Lowest quota use |
| **Fast** | Lower-latency work on a lighter model | Intermediate quota use |
| **Max** | The most demanding reasoning and multimodal work | Highest quota use |

The profiles and models available to you can vary by plan and workspace.
Some workspaces also expose a **Custom** submenu with direct model choices.

You can change the profile for an existing task when the agent is idle. A busy
task keeps its current profile until that run finishes.

> [!TIP]
>
> Start with Standard. Move to Fast when latency matters more than depth, or Max
> when the task needs stronger reasoning, image/PDF input, or a difficult review.

## Computational work

Biomni runs code in an isolated cloud workspace. It can use Python, R, and shell
tools, create files, and execute notebook cells. For larger workloads it can
start additional CPU, high-memory, or GPU machines and submit supported HPC
tools and pipelines.

Examples include:

* parallel processing across samples;
* high-memory assembly and genomics workflows;
* GPU-backed structure prediction and design; and
* versioned nf-core pipelines for common sequencing analyses.

Tasks started through Biomni MCP can use the same supported HPC tools as tasks
started on web or desktop. This includes RFDiffusion, RFAntibody, and
RFD4-Proteina where they are enabled for your deployment. Tool availability,
account permissions, and biosecurity screening apply to every task.

You do not need to select a machine manually for ordinary work. Describe the
dataset and constraints; Biomni chooses an execution approach and reports
long-running background activity in the task.

## Usage and concurrency

Model calls and compute both contribute to usage. A complex task can consume
more than a short question even when each begins with one message. Plan limits
and concurrent-task capacity are shown in Biomni Lab and vary by plan.

See the [Pricing FAQ](/pricing-faq) for self-serve plan and billing details.


# Pipelines
Source: https://docs.biomni.phylo.bio/features/pipelines

Prepare, run, and review scientific workflows with Nextflow

Pipelines run a defined series of analysis steps across samples. Biomni can help
prepare inputs and interpret results, while **Nextflow** coordinates the
workflow on managed cloud compute.

Phylo supports selected versioned pipelines from the [nf-core
community](https://nf-co.re/) and compatible custom Nextflow workflows. Open
**Pipelines** from the main navigation to browse established pipelines available
in your workspace.
You can also start from a pipeline example in **Capabilities**.

## Prepare a run

In a task, add a pipeline from **+ Add → Resources** and reference your input
files with `@`. Ask Biomni to check the inputs and configuration. For example:

```text theme={null}
Prepare an nf-core/rnaseq run for these files. Check sample matching and
parameters, then show me the configuration before starting.
```

Before launch, review that:

* the pipeline matches your analysis;
* samples and metadata are correct; and
* references and parameters fit your study.

You can also provide a custom workflow. Include its `main.nf`, required modules
or config files, and input data. Ask Biomni to check the files and explain the
workflow's expected inputs and outputs.

## Monitor and review

In the task, you can follow:

* overall and process-level progress;
* logs and error details; and
* reports and outputs when available.

If a run fails, ask Biomni to explain the error and suggest a next step. You may
be able to resume completed work or need to correct the inputs and run again.

Review completed outputs alongside the scientific results. Run details and
output lineage can help identify which process produced a file. Keep the
pipeline version, inputs, references, and parameters with your analysis.

To explore the run lifecycle without your own sequencing files, ask Biomni to
use the `nf-core/rnaseq` test profile:

```text theme={null}
Run nf-core/rnaseq with its test profile. Show me the configuration before
launching, then summarize the run and outputs.
```

Check that the method and parameters fit your research question. Validate new
or modified workflows on representative data. Biomni can help prepare and
interpret a run, but researchers remain responsible for reviewing the method
and results.

[Nextflow](https://www.nextflow.io/) is an open-source workflow system developed
by [Seqera](https://seqera.io/) and its contributor community. Biomni supports
Nextflow and selected [nf-core](https://nf-co.re/) pipelines. Phylo and Biomni
are independent products and are not affiliated with, sponsored by, or endorsed
by Seqera or nf-core.


# Projects & Drive
Source: https://docs.biomni.phylo.bio/features/projects-and-drive

Organize related tasks, files, results, and project-wide instructions

Projects keep related research in one place. Each project contains tasks and
project-scoped files; it can also provide context, instructions, and default
Skills to every new task.

## Quick Tasks and named projects

**Quick Tasks** is the default project for one-off work. It behaves like a
normal project, including file sharing between its tasks, and you can rename
it like any other project.

Create a named project when work has a durable research question, dataset, or
team. Open the project selector in the sidebar and choose
**Create a new project**.

## Tasks

A task is one conversation with Biomni. Within a project, each task has its own:

* message and execution history;
* generated results;
* plan, compute activity, and notes; and
* model profile.

The project sidebar shows its tasks and current activity. Use separate tasks for
analyses with different goals or assumptions; keep follow-up refinement in the
same task.

## Project files and Results

Uploaded and imported files belong to a project. Biomni can use project files in
that project's tasks, and you can select an existing file from **+ Add** without
uploading it again.

Generated task output appears in **Results** and remains associated with the
project. Depending on the file type, you can preview, download, rename, move, or
delete it. Internal execution artifacts are hidden from normal file views.

> [!NOTE]
>
> Access follows the project. A file from another project must be copied, imported,
> or explicitly selected through an available product flow before the current
> task can use it.

## Drive

Drive is the project-level file browser. Use it to:

* browse folders, uploads, and generated files;
* upload files or folders;
* preview and download supported formats;
* rename, move, or delete content when your role permits; and
* inspect project file activity.

Cloud imports copy external files into project storage. See
[Cloud Storage](/features/cloud-storage) for supported import flows.

## Project settings

Open **Settings → Projects** and select a project.

### Project context

Describe durable facts Biomni should know in every new task, such as the study,
organism, assay, cohort, or dataset conventions.

### Custom instructions

Set project-specific response or workflow requirements. These are more specific
than personal instructions but cannot override safety controls.

### Auto attached Skills

Choose Skills that should be attached to the first message of every new task.
Keep this list short and limited to workflows the project genuinely uses by
default.

> [!NOTE]
>
> Project settings are captured when a task is created. Editing them affects new
> tasks; existing tasks keep the context, instructions, and Skill versions they
> started with.

## Collaboration

Team workspaces can share a project as Viewer, Editor, or Admin.
Project tasks and files inherit that access. Only the person who currently has
chat access can steer a task, and only the task creator can edit its notes.

See [Collaboration](/features/collaboration) for the complete role model.


# Resources
Source: https://docs.biomni.phylo.bio/features/resources

Point Biomni at scientific databases, tools, and packages

Resources tell Biomni which scientific database, tool, or software package
matters for your request. Adding a resource gives Biomni context; sending the
request starts the work.

The Resources panel is the source of truth for the catalog available in your
workspace. It is updated more often than this guide and can vary by plan.

## Start here

Not sure a Resource is what you need? Pick the starting point that matches your
next step:

| You want to… | Start with | Where to find it |
| - | - | - |
| Follow a reusable scientific method that adapts to your files, such as a DESeq2 differential-expression workflow | **[Skill](/features/skills-and-capabilities)** | **Skills** in the left navigation, or **+ → Skills** in the composer (type `+`) |
| Run an established, versioned Nextflow workflow the same way every time, such as nf-core/rnaseq | **[Pipeline](/features/pipelines)** | **Pipelines** in the left navigation, when pipelines are available in your workspace |
| Point Biomni at a specific database, tool, or package, such as PubMed | **[Resource](/features/resources)** | **+ → Resources** in the composer (type `@`) |
| Give Biomni your own data | **Files** | **+ → Upload files**, or **Select from uploaded files** |

You can combine them. For example, attach a Skill and a database Resource to
the same request, together with your files.

## Browse resources

1. In a task, select **+** in the composer and choose **Resources**, or type `@`
   in the message box.
2. Choose a section: **All**, **Database**, **Tools**, or **Package**. When
   pipelines are available in your workspace, **Pipelines** and **Modules**
   (Nextflow modules and subworkflows) appear too.
3. Search by name and select a resource. It is added to your message.
4. Say how Biomni should use it, then send.

The sections hold:

* **Database** — scientific data sources such as PubMed, UniProt, PDB, Ensembl,
  ClinVar, GEO, Open Targets, and GWAS Catalog.
* **Tools** — managed scientific functions and HPC tools.
* **Package** — Python, R, and command-line packages available for code-based
  analysis.

To browse the catalog on its own page, select **Open resources page** at the
bottom of the panel, where shown. The page groups resources into Databases,
Tools, and Packages.

## Example: an evidence table from PubMed

Add **PubMed** from the Database section, then ask:

```text theme={null}
Search @PubMed for randomized studies published since 2022 on this intervention.
Build an evidence table with population, endpoint, effect size, and limitations.
```

When the answer arrives, open a few of the cited studies and check that each row
matches its source.

Another example, for a tool:

```text theme={null}
Use @STAR for alignment and explain the reference build and parameters before
submitting the run.
```

## Attaching a resource does not run it

A resource is context for the request. Biomni still chooses and executes the
appropriate tool calls while working. If you require a specific method, say so
explicitly and explain any fixed parameters or validation criteria. Afterwards,
ask Biomni which databases and tools it actually used.

> [!TIP]
>
> You usually do not need to attach common software by name. Attach a resource when
> the source or method is part of the scientific requirement.

## Managed compute and pipelines

Compute-intensive tools and nf-core pipelines run outside the ordinary analysis
workspace. Biomni searches the current registry, reads the selected tool or
pipeline guide, submits the job, and reports completion back to the task.

Availability, versions, GPU types, and resource limits can change by plan and
workspace. Use the in-product catalog rather than a copied tool list when
planning a workflow.

To find a pipeline, open **Pipelines** in the left navigation. See
[Pipelines](/features/pipelines) for guidance on preparing and reviewing a
Nextflow run.


# Scientific Review
Source: https://docs.biomni.phylo.bio/features/scientific-review

Ask a second agent to critique a completed Biomni response

Scientific Review asks a separate reviewer agent to examine a completed response.
The reviewer looks for scientific errors, unsupported claims, incorrect use of
data, missing limitations, and places where the evidence does not support the
conclusion.

## Run a review

1. Wait for Biomni to finish its response.
2. Select **Review** on the latest answer.
3. Keep the task open or continue elsewhere while the review runs in the
   background.
4. Read the review when it appears beneath the answer. To cancel a review in
   progress, select **Stop**.

Only one scientific review runs at a time for a task. The Review action is not
available while the agent is still working or when there is no completed answer
to assess.

## Automatic review

Turn on **Auto scientific review** in **Settings → Personalization** to let
Biomni request a review on its own after a turn. The setting is marked
Experimental and is off until you turn it on.

## Use the findings

Treat the review as a critique, not a certification. It can identify issues and
suggest corrections, but it is still generated by an AI system.

Useful follow-ups include:

```text theme={null}
Address the review's concerns about the control group and rerun the analysis.
```

```text theme={null}
Which review findings change the conclusion, and which only affect presentation?
```

```text theme={null}
Create a revised report that distinguishes observed results from interpretation.
```

## Review checklist for important work

For clinical, regulatory, safety-critical, or publication-ready work:

* inspect the underlying data and generated files;
* open and verify cited sources;
* confirm tool versions, parameters, and statistical assumptions;
* reproduce key calculations independently; and
* have a qualified human review the final conclusions.

> [!WARNING]
>
> Scientific Review reduces the chance that an issue goes unnoticed. It does not
> replace expert review or independent validation.


# Skills
Source: https://docs.biomni.phylo.bio/features/skills-and-capabilities

Start from a proven scientific workflow

Biomni combines a general research agent with reusable **Skills**. Use a Skill
when you want Biomni to follow a tested, reusable workflow instead of
improvising one.

## Start here

> [card] [Use a Skill](#use-a-skill-in-a-task)
>
> Find a workflow and attach it to a task.

> [card] [Create or adapt a Skill](#create-your-own-skill)
>
> Copy a Skill, upload a folder, or build one with Biomni.

> [card] [Share a Skill](#share-a-skill)
>
> Share a Skill you own with your team, or submit it to Community.

### Skill, Pipeline, or Resource?

| You want to… | Start with | Where to find it |
| - | - | - |
| Follow a reusable scientific method that adapts to your files, such as a DESeq2 differential-expression workflow | **[Skill](/features/skills-and-capabilities)** | **Skills** in the left navigation, or **+ → Skills** in the composer (type `+`) |
| Run an established, versioned Nextflow workflow the same way every time, such as nf-core/rnaseq | **[Pipeline](/features/pipelines)** | **Pipelines** in the left navigation, when pipelines are available in your workspace |
| Point Biomni at a specific database, tool, or package, such as PubMed | **[Resource](/features/resources)** | **+ → Resources** in the composer (type `@`) |
| Give Biomni your own data | **Files** | **+ → Upload files**, or **Select from uploaded files** |

You can combine them. For example, attach a Skill and a database Resource to
the same request, together with your files.

## Use a Skill in a task

Attach a Skill when you know which workflow you want. Not sure which one fits?
[Browse the Skill Hub](#browse-the-skill-hub) first: search by scientific goal
and read a Skill's Overview before you use it.

1. In the composer, select **+** and choose **Skills**, or type `+` directly in
   the message box.
2. Search or browse the catalog. Skills are grouped by area, such as
   Transcriptomics, Genomics & Genetics, and Molecular Design.
3. Select a Skill. It appears as a chip above your message, usually with a
   starter prompt you can edit.
4. Describe your data and goal, add or select your files, and send.

![The composer's + menu with Upload files, Resources, Skills, and Connectors options](https://mintcdn.com/phylo/zbyIb9gGnwwgtfmB/images/skills-composer-add-menu.png?fit=max\&auto=format\&n=zbyIb9gGnwwgtfmB\&q=85\&s=3a00c713efaa56025f9c96b376212dcd)

The + menu opens the Skills panel.

![The Skills panel with a search box, category list, and skill cards](https://mintcdn.com/phylo/zbyIb9gGnwwgtfmB/images/skills-composer-panel.png?fit=max\&auto=format\&n=zbyIb9gGnwwgtfmB\&q=85\&s=2ed156e9edfe444c7eb0830f2ad96c28)

Search or browse Skills by category.

![The composer with the adme-ml-modeling skill attached as a chip above an editable starter prompt](https://mintcdn.com/phylo/zbyIb9gGnwwgtfmB/images/skills-composer-chip.png?fit=max\&auto=format\&n=zbyIb9gGnwwgtfmB\&q=85\&s=a32134f4eeda4f5cca6ca3fae8b0647e)

The selected Skill sits above your message as a chip, with an editable starter prompt.

For example, with a differential-expression Skill attached:

```text theme={null}
Using the attached Skill, compare treated and control samples in @counts.csv
using the sample groups in @metadata.csv. Show me the design, contrast, and
filtering choices before running anything.
```

Biomni reads the attached Skill when it starts that turn and follows its
workflow together with your request. If you asked to see choices first, check
them before you approve the work. To confirm which Skill and steps were used,
ask Biomni in a follow-up or compare its plan with the Skill's Overview.

### Explicit and implicit use

You can name a Skill, or let Biomni pick one:

| Use | Example request |
| - | - |
| **Explicit** — you name the Skill | “Use `cis-eqtl-analysis` with these files.” |
| **Implicit** — Biomni picks the Skill | “I have genotype, expression, and covariate files. Help me run a cis-eQTL analysis.” |

Attaching a Skill from the panel works like naming it. For implicit use, Biomni
matches your request against each Skill's name and description. The
description usually decides the match, so say clearly what the Skill is for.

![Explicit use attaches a chosen Skill as a composer chip; implicit use lets Biomni match the request with Skill descriptions.](https://mintcdn.com/phylo/hnQ3ag3949XqypFV/images/skills-guide/fig-2-explicit-vs-implicit-use.png?fit=max\&auto=format\&n=hnQ3ag3949XqypFV\&q=85\&s=cd9d18b8ca75d145b434ec62b2d89a61)

Two ways a Skill joins your task.

> [!TIP]
>
> Attach only the Skills the current task needs: extra instructions use up context
> and can pull the analysis in conflicting directions. You can attach several
> Skills, and your prompt can limit Biomni to specific ones or ask it to skip an
> optional step.

## Browse the Skill Hub

Select **Skills** in the left rail to see every Skill available to you. Search
by name or keyword, filter by category, or filter by source:

* **Mine** — Skills you created or copied.
* **Biomni Lab** — Skills curated by Phylo.
* **Team** — Skills shared in your organization.
* **Community** — Skills published by other Biomni Lab users.
* **Shared with Me** — Skills someone shared with you directly. Shown in
  organization workspaces when you have any.

Each card says what the Skill is for and when it was last updated. **New skill**
(top right) starts your own.

![The Skill Hub with a search box, source filters, and cards for curated skills such as bulk-omics-clustering and flow-cytometry-analysis](https://mintcdn.com/phylo/zbyIb9gGnwwgtfmB/images/skills-hub.png?fit=max\&auto=format\&n=zbyIb9gGnwwgtfmB\&q=85\&s=b261ce2211b82469edcb5b06200859ad)

The Skill Hub, filtered to Skills curated by Biomni Lab.

![Skill Hub sources Mine, Biomni Lab, Team and Community, with Overview, Files, Open in chat and Copy skill actions.](https://mintcdn.com/phylo/hnQ3ag3949XqypFV/images/skills-guide/fig-3-skill-hub-sources-and-actions.png?fit=max\&auto=format\&n=hnQ3ag3949XqypFV\&q=85\&s=70afa5f4f9a98ae76951d9176bf1c110)

Where Skills come from, and what you can do with one.

### Inspect and copy a Skill

Select any card to open the Skill and see exactly what Biomni will follow:

* **Overview** shows the primary markdown, the guidance Biomni loads.
* **Files** lists the whole package: `SKILL.md`, references, scripts, and
  examples.
* **More (⋯) → Open in chat** starts a task with the Skill attached.
* **More (⋯) → Copy skill** creates your own editable version of a Biomni Lab,
  Team, or Community Skill. It is the quickest way to adapt a curated Skill to
  your lab's conventions. It isn't shown for Skills you already own.

![A skill detail page for coexpression-network with Overview and Files tabs, package files listed, and a menu showing Open in chat and Copy skill](https://mintcdn.com/phylo/zbyIb9gGnwwgtfmB/images/skills-detail.png?fit=max\&auto=format\&n=zbyIb9gGnwwgtfmB\&q=85\&s=b8205e4d0281f050e79db70cc2547916)

A Skill's detail page, with the Files tab and the More menu open.

## Auto-attach Skills to a project

Project admins can attach Skills automatically to the first message of every new
task in a project. This is useful when a team always works with the same
workflow.

1. Select the gear next to the project name and choose **Project settings**, or
   open **Settings → Projects** and select the project.
2. Scroll to **Auto attached skills** and select **Add auto attached skill**.
3. Choose the Skills. Changes save automatically.

Project settings are captured when a task is created, so changes apply to new
tasks only, not existing conversations. Members can still add other Skills inside
a task.

![The Auto attached skills section of project settings with an Add auto attached skill button](https://mintcdn.com/phylo/zbyIb9gGnwwgtfmB/images/skills-project-auto-attach.png?fit=max\&auto=format\&n=zbyIb9gGnwwgtfmB\&q=85\&s=d3287f6dc1e107d01aa3a5c7a3e32fca)

Auto attached skills in project settings.

![Project admins set auto-attached Skills for new tasks; existing tasks keep the Skills they started with.](https://mintcdn.com/phylo/hnQ3ag3949XqypFV/images/skills-guide/fig-4-project-auto-attach.png?fit=max\&auto=format\&n=hnQ3ag3949XqypFV\&q=85\&s=546e7618e110b45da6dacc621ad9fd9c)

Auto-attached Skills apply to new tasks only.

## What a Skill is

A Skill is a generalizable, flexible set of instructions for the agent: a
packaged workflow for a specific type of work. Skills range in scope from a
single narrow step to a full end-to-end analysis.

```text theme={null}
cis-eqtl-analysis/
├─ SKILL.md
├─ references/
├─ scripts/
├─ examples/
└─ templates/
```

* **`SKILL.md` is the entry point.** It names the Skill, says when to use it, and
  tells the agent what to do. It is the only required file.
* **Supporting files are optional.** References hold detailed methods and
  literature, scripts handle small deterministic steps such as validation or
  file conversion, and examples and templates show the expected output.
* **The name and description decide when it is used.** Biomni sees each Skill's
  name and description, then loads the full instructions when your request
  matches. The description carries most of the signal, so write it carefully.
* **Your Skills are private by default.** Skills you create, upload, or copy are
  visible only to you until you share them with your team or submit them for
  Community publication. See the [privacy policy](https://phylo.bio/privacy) for
  how Phylo handles your data.

![A Skill folder with required SKILL.md and optional references, scripts, examples and templates; Biomni scans descriptions, loads the matching Skill and opens supporting files when needed.](https://mintcdn.com/phylo/hnQ3ag3949XqypFV/images/skills-guide/fig-1-anatomy-of-a-skill.png?fit=max\&auto=format\&n=hnQ3ag3949XqypFV\&q=85\&s=4cc1df316513a37d388e2e4905e44220)

What's inside a Skill, and how Biomni uses it.

## Create your own Skill

In the Skill Hub, select **New skill**. You have three starting points:

* **Create with Biomni Lab** builds the Skill in conversation with the agent.
  Best for new workflows.
* **Upload skill** brings in an existing Skill folder: `SKILL.md` plus any
  supporting files.
* **Copy skill**, on the detail page of a Biomni Lab, Team, or Community Skill,
  gives you an editable version to adapt.

![The New skill button open, showing Upload skill and Create with Biomni Lab](https://mintcdn.com/phylo/zbyIb9gGnwwgtfmB/images/skills-new-skill-menu.png?fit=max\&auto=format\&n=zbyIb9gGnwwgtfmB\&q=85\&s=0e6fb6c1f68db5a3c2b00161ac2c5af3)

The New skill menu.

### Build it in stages, then create it

Settle the plan before anything is written. Phylo builds its own Skills with
these four prompts to Biomni:

1. **Define the task.** Ask Biomni to describe the scientific task, its use
   cases and boundaries, and how it differs from related Skills. Add “Do not
   create the skill yet.”
2. **Agree on the contract.** Have it propose required inputs, expected outputs,
   assumptions, when to ask you for clarification, and when to stop.
3. **Choose the methods.** Ask it to review the available tools and literature,
   then name the approved methods, parameters, and any licensing limits.
4. **Create, then test.** Only now ask it to create the Skill, then
   [test it](#test-before-you-rely-on-it). Refine over several sessions rather
   than one long one.

![Create with Biomni, upload or copy a Skill, then define the task, agree on inputs and outputs, choose methods, create and test.](https://mintcdn.com/phylo/hnQ3ag3949XqypFV/images/skills-guide/fig-5-ways-to-create-a-skill.png?fit=max\&auto=format\&n=hnQ3ag3949XqypFV\&q=85\&s=709fcc6c42294f264aff9dda5a7c099a)

Three ways to start, then four stages to build.

### What a scientific Skill should standardize

Aim to reduce improvisation and make consequential choices visible.

| Area | What to standardize |
| - | - |
| **Scope** | The analyses it supports and the inputs it requires. |
| **Methods** | Valid methods and tools, and the choices a scientist must make. |
| **Checks** | Checks before running, and stop conditions for bad data. |
| **Reporting** | Outputs, parameters, provenance, and limitations. |

## Test before you rely on it

![Standardize scope, methods, checks and reporting; test routing, execution and scientific correctness, with optional scientific review at extra credit cost.](https://mintcdn.com/phylo/hnQ3ag3949XqypFV/images/skills-guide/fig-6-standardize-and-test.png?fit=max\&auto=format\&n=hnQ3ag3949XqypFV\&q=85\&s=f0691b4322e2fac2982a4152b8c850f7)

What to standardize, and how to test it.

| Test | What to check |
| - | - |
| **Routing** | Explicit and implicit requests activate the Skill, including vague ones. Adjacent requests, such as raw reads for an eQTL Skill, do not. |
| **Execution** | A small valid dataset reaches the expected outputs. Invalid inputs, such as mismatched sample IDs or missing covariates, make the Skill stop instead of improvising. |
| **Scientific correctness** | Results match an approved reference run, a known positive signal and a negative control behave as expected, and repeated runs agree where they should. |

Biomni can generate synthetic test data and help design the tests. For
substantial work, turn on **Auto scientific review** (**Settings →
Personalization**) so a second agent audits the approach. It uses extra credits.
See [Scientific Review](/features/scientific-review).

### Quick tips

* Keep the first version narrowly scoped, and widen it only once it works
  reliably.
* Write the description with positive and negative boundaries: it is the main
  signal Biomni uses to decide when the Skill applies.
* State parameters in `SKILL.md`, report them in outputs, and turn each failure
  into a new test case.
* Record the Skill version with each analysis, and retest before using a revised
  Skill broadly.

## Share a Skill

Skills you create, upload, or copy start private. To share a Skill you own, open
it in the Skill Hub and select **More (⋯)**:

* **Share with team** (in team workspaces) makes it available to your team
  right away. In organization workspaces this reads **Share with
  organization**, and **Share with specific users** is also available.
* **Make private** stops sharing it.
* **Publish skill** asks Phylo to review it for **Community**. The Skill shows
  **Publish pending** until the review finishes, then **Published** or **Publish
  rejected**. **Cancel** withdraws a pending or rejected request. Community
  publishing isn't available in organization workspaces.
* After it is published, your edits stay in your own draft. **Republish** submits
  them for a new review, and **Unpublish** removes the Skill from Community.

**Copy skill** gives you a separate copy that you own. Changes to the original
don't update your copy.

## Skills or pipelines?

| | Skill | Pipeline |
| - | - | - |
| **Behavior** | Guided and exploratory: the agent decides the steps | Deterministic and repeatable: same input, same output |
| **Use when** | The right path depends on context, the work is exploratory, or inputs vary and need interpretation | The steps are established, execution must be consistent, or samples run in parallel at scale |

They work best together: a Skill can prepare, launch, and check a
[pipeline](/features/pipelines) run. When a Skill keeps taking the same path,
harden that path into a pipeline and have the Skill call it.

![Skills adapt to context, pipelines repeat established steps at scale, and a Skill can launch a pipeline and check its results.](https://mintcdn.com/phylo/hnQ3ag3949XqypFV/images/skills-guide/fig-7-skills-or-pipelines.png?fit=max\&auto=format\&n=hnQ3ag3949XqypFV\&q=85\&s=67458da638221b80e4de83dfdc86fe67)

Skills adapt; pipelines repeat. A Skill can launch a pipeline and check its results.

> [card] [Browse resources](/features/resources)
>
> Databases, tools, and packages to add to a request.

> [card] [Write a strong request](/how-to-prompt)
>
> Add the context and constraints a workflow needs.


# How to Prompt
Source: https://docs.biomni.phylo.bio/how-to-prompt

Give Biomni a clear scientific goal, the right inputs, and useful constraints

You do not need to write a formal protocol before starting. A strong request
makes the scientific goal and evidence boundary clear, then lets Biomni plan the
implementation.

## Start with the outcome

Say what you need to learn, decide, or deliver.

> [tab] Too broad
>
> ```text theme={null}
> Analyze my data.
> ```

> [tab] Actionable
>
> ```text theme={null}
> Identify genes that differ between treatment and control in @counts.csv,
> then create a ranked result table and a publication-ready volcano plot.
> ```

## Include the experimental context

Add details that change the interpretation or method:

* organism, reference build, assay, and tissue or cell type;
* cohort definitions, controls, replicates, and batch structure;
* units, column meanings, and missing-value conventions;
* primary endpoint or research question; and
* whether the work is exploratory, confirmatory, or intended for publication.

```text theme={null}
These are paired tumor and adjacent-normal RNA-seq samples from 12 patients.
Patient ID is the blocking variable in @metadata.csv. Use GRCh38 annotations and
report both effect size and adjusted p-value.
```

## Attach or mention the evidence

Use **+ Add** for files, folders, cloud imports, Skills, resources, and
connectors. Type `@` to search files and scientific resources, or `+` to search
Skills.

Do not rely on a filename alone when its structure is ambiguous. Explain which
sheet, columns, groups, or identifiers matter.

## State constraints without over-specifying

Specify a method when it is scientifically required. Otherwise, state the
constraint and ask Biomni to choose and justify the method.

```text theme={null}
Use a method appropriate for paired count data. Before running it, explain the
design formula, filtering rule, and multiple-testing correction you chose.
```

Useful constraints include:

* required or prohibited methods;
* quality thresholds and inclusion criteria;
* resource or runtime limits;
* databases or date ranges to search;
* output format, dimensions, and naming; and
* citation or reproducibility requirements.

## Ask for inspectable outputs

Request the artifacts needed to audit or continue the work:

```text theme={null}
Return the full result table as CSV, the analysis notebook, SVG and PNG versions
of each figure, and a short README describing inputs, software, parameters, and
output files.
```

For literature or database research, ask for linked sources next to the claims
they support. For data analysis, ask Biomni to separate observed results from
interpretation.

## Use follow-up turns

Keep related refinement in the same task so Biomni can use the conversation and
generated files.

```text theme={null}
The plot is correct, but label only the ten genes with the smallest adjusted
p-values and increase the axis-label size. Do not rerun the statistical model.
```

If the goal changes substantially, start a new task. This keeps the evidence,
assumptions, and results for each analysis easier to review.

## When you are unsure

Ask Biomni to identify missing information before it acts:

```text theme={null}
I want to test changes across three timepoints in this RNA-seq experiment. Read
@metadata.csv and tell me what design details you still need before choosing a
model. Do not run the analysis yet.
```

For high-impact conclusions, finish with an explicit verification request and
run [Scientific Review](/features/scientific-review).


# Introduction
Source: https://docs.biomni.phylo.bio/introduction

A research workspace where an AI agent can analyze data, run tools, and produce verifiable results

Biomni Lab is an AI research workspace for biomedical and life-science work. You
describe a goal in natural language; Biomni can inspect your files, search
scientific sources, write and run code, use specialized tools, and return
results in the same task.

## What you can do

Biomni supports work such as:

* literature and database research with linked sources;
* statistical analysis and publication-ready visualization;
* genomics, transcriptomics, single-cell, and multi-omics workflows;
* protein structure prediction and molecular design;
* custom Python, R, and shell-based analysis; and
* larger CPU, high-memory, GPU, or pipeline workloads.

The exact resources, models, and integrations available depend on your plan and
workspace configuration.

## How work is organized

> [card] [Projects](/features/projects-and-drive)
>
> Group related tasks and files around a research question or dataset.

> [card] Tasks
>
> Keep one analysis or research thread in a focused conversation.

> [card] [Skills](/features/skills-and-capabilities)
>
> Attach reusable, domain-specific workflows to a request.

> [card] Results
>
> Preview, download, and continue working with generated files.

Every account starts with a **Quick Tasks** project for one-off work. Create
additional projects when tasks should share files, context, instructions, or
collaborators.

## What happens after you send a request

Biomni can plan the work, start an isolated cloud workspace when computation is
needed, and show its tool activity as the task progresses. Generated artifacts
appear in the conversation and Results panel. Long-running compute can continue
as background work and report back to the same task.

Biomni is an assistant, not an authority. Inspect source material, parameters,
generated files, and important conclusions. For high-stakes work, use
[Scientific Review](/features/scientific-review) and independent expert review.

## Start here

> [card] [Quickstart](/quickstart)
>
> Run a first task and work with its output.

> [card] [How to prompt](/how-to-prompt)
>
> Give Biomni the context and constraints it needs.

> [card] [Skills](/features/skills-and-capabilities)
>
> Start from a reusable scientific workflow.

> [card] [Models & Compute](/features/models-and-compute)
>
> Choose a model profile and understand execution.


# Pricing FAQ
Source: https://docs.biomni.phylo.bio/pricing-faq

Frequently asked questions about Biomni Lab pricing, plans, and billing

## What does Phylo cost?

Phylo offers an Individual Free plan at no cost, an Individual Pro plan at \$100/month, and a Team plan at \$100/month per standard seat. Researchers at eligible academic or research institutions receive 50% off eligible paid plans, paying \$50/month for Individual Pro or \$50/month per academic Team seat.

Monthly and annual billing are both available for paid plans; annual plans are billed once per year.

## What counts as "usage" and what does "10x daily usage" mean?

Usage is based on the underlying LLM and compute resources consumed by your requests — not a simple message count. The actual usage per request varies highly depending on task complexity; a quick Q\&A uses far less than a multi-step data analysis. Pro users get 10x the daily usage allowance of Free users. You can check your current daily usage on the [Settings](https://biomni.phylo.bio/settings) page.

Pro includes a standard daily usage allowance of 10x the Free plan's allowance.
Once you reach that allowance, additional requests may be queued. The queue
provides generous extra capacity but is not an unlimited-usage guarantee. If
the daily limit or queue capacity is reached, new requests may be refused until
usage resets or capacity becomes available. Queue limits may change over time.

To get more done each day, use a mix of models. Open-weight models generally
consume less usage than frontier models, so they are a good choice for most
queries. Reserve frontier models for tasks that open-weight models cannot
complete.

## Individual Free & Pro Plan

### What’s the difference between Individual Free and Pro?

The Individual Free plan has no monthly subscription fee and includes a lower daily usage allowance. The Individual Pro plan costs \$100/month, or \$50/month with the academic discount, and includes a higher daily usage allowance and higher concurrent task limits.

### How does the academic discount work?

The 50% academic discount is automatically applied based on your email address. If you sign up with a university or recognized research institute email, you'll be charged \$50/month instead of \$100/month for Pro. No coupon code or manual application needed.

### Which institutions qualify for the academic discount?

We support 10,000+ universities across 200+ countries, plus select non-university research institutes. Eligibility is determined automatically against our supported institution list, which covers common academic domains like `.edu`, `.ac.uk`, `.edu.au`, and many more.

### How do I know if the academic discount is applied to my account?

Go to [Settings](https://biomni.phylo.bio/settings) and start the upgrade flow — the price shown will reflect the academic discount (\$50/month instead of \$100/month) if your email qualifies. No payment is charged until you explicitly confirm.

### My university or institution is not recognized. What should I do?

Our list covers 10,000+ universities worldwide and should be comprehensive for most researchers. If your institution is not covered, please reach out to us at [billing@phylo.bio](mailto:billing@phylo.bio) and we will try to add new universities and institutions based on availability.

### How do I upgrade to Pro?

Go to [Settings](https://biomni.phylo.bio/settings), click "Upgrade to Pro," and enter your payment details via Stripe. We accept all major credit cards. Your Pro plan activates immediately after payment.

### How do I update my payment method?

Go to your [Settings](https://biomni.phylo.bio/settings) page → Billing tab → Payment method item, then click the View button. From there, you can click Update to update your credit card.

### How do I cancel my Pro subscription?

You can downgrade from [Settings](https://biomni.phylo.bio/settings) at any time. Your Pro access continues until the end of your current billing period, then you'll move to the Free plan. No penalties or cancellation fees.

### What happens when I hit my daily usage limit?

Pro includes 10x the Free plan's daily usage. Once that allowance is used,
additional tasks may be queued and run as capacity becomes available. The queue
provides generous extra capacity but is not unlimited. If the daily limit or
queue capacity is reached, new requests may be refused until usage resets or
capacity becomes available. Queue limits may change over time.

### Can I get a refund if I cancel my Pro subscription?

When you cancel, your Pro access continues until the end of the period you already paid for, and you will not be charged again. Mid-cycle cancellations are not automatically prorated. A full refund for the current billing period may be available if you request it within 3 days of payment on a monthly plan (14 days on an annual plan) and have made minimal use of Biomni Lab since the charge. See our [Refund Policy](/support/refund-policy) for the full criteria and how to request a refund.

### Is my payment information secure?

Yes. Phylo does not store your card number. All payment processing is handled by Stripe, and your card details never touch our servers.

## Team Plan

### What does the Team plan include?

The Team plan is billed per workspace and gives each member Pro-level access in that shared workspace. Pricing is \$100/month per standard seat and \$50/month per academic seat.

### Do team members get their own usage limits?

Yes. Usage limits are enforced per user, not pooled across the workspace. Team members currently get the same daily allowance as Individual Pro users.

### How does academic pricing work?

Academic pricing is determined per member based on that member’s email address. This means one team can have a mix of standard seats at \$100/month and academic seats at \$50/month at the same time.

### When am I charged for seats?

Team billing follows a recurring cycle anchored to the date the team subscription starts. Teams can be billed **monthly** or **annually**. At each renewal you are charged for the current number of seats for the upcoming period — the next month on monthly billing, or the next year on annual billing.

When you add a member during the billing cycle, that seat is prorated for the remainder of the cycle. When that prorated charge is collected depends on your plan:

* **Monthly teams:** the prorated amount is added to your next monthly invoice.
* **Annual teams:** the prorated amount is billed at the time the member joins, as a separate charge covering the rest of your annual term — rather than waiting until your annual renewal.

### When does adding a member increase my bill?

Adding a member increases billing when that member actually joins the workspace, not when you send the invitation. On monthly billing the prorated charge appears on your next invoice; on annual billing it is charged at the time the member joins. If you have already removed someone earlier in the same billing cycle and are simply filling that slot back to the same peak seat count, there is usually no additional seat-change charge.

### What happens when I remove a member?

Removing a member revokes their access immediately. It does not create a prorated refund or credit for the current billing cycle — your team keeps that seat for the rest of the period you already paid for, and the lower seat count is reflected at your next renewal. On annual billing this means a removed seat is not credited for the remainder of the year, and the reduced seat count takes effect at your annual renewal.

### If I swap one member for another in the same cycle, do I pay extra?

Usually no. Our billing uses a high-watermark model for mid-cycle seat changes, on both monthly and annual plans. If your team already reached a given seat count earlier in the cycle, removing one member and adding another back to that same count generally does not create an extra charge. Additional prorated charges only happen when the team exceeds its previous peak seat count in that billing cycle. On annual plans this free-swap window covers your entire annual term, not just a single month.

### Can you show me an example invoice for team seat changes?

Yes. Here is an example using our current Team pricing and billing behavior for standard seats:

* A team starts its billing cycle with **3 standard seats**
* Standard seats cost **\$100/seat/month**
* On day 10 of the cycle, the team adds **1 member**, bringing the team to **4 seats**
* On day 15, the team removes **1 member**, bringing the team back to **3 seats**
* On day 20, the team adds **1 member**, bringing the team back to **4 seats**
* On day 25, the team adds **1 more member**, bringing the team to **5 seats**

On the next invoice, the team would be charged for:

* **5 seats for the new month** = `5 × $100 = $500`
* **1 prorated seat from day 10 to the end of the cycle** = about `21/30 × $100 = $70`
* **1 additional prorated seat from day 25 to the end of the cycle** = about `6/30 × $100 = $20`

**Total: about \$590**

In practical terms, if someone leaves your team and you later replace them during the same billing cycle, you generally will not be charged again just for returning to the same seat count. You would only see an additional prorated charge if your team grows beyond the highest number of seats you already reached in that cycle.

**On annual billing, the same high-watermark logic applies — only the timing changes.** Your seats are billed up front for the year, and any seat addition above your previous peak is billed at the time the member joins (a prorated charge covering the rest of your annual term), rather than waiting for your annual renewal. Removing and re-adding members below your peak remains free for the entire year.

## Invoices & Billing Details

### Can invoices be made out to my university or company?

Yes. When you upgrade, you are asked for the billing name and address that should appear on your invoices — this can be your institution or employer rather than you personally. This is what invoices render as "Bill to."

### Can I add a VAT or tax ID to my invoices?

Yes, outside the US. During checkout you can choose to purchase as a business and enter your VAT number or local equivalent, and it will appear on your invoices. Stripe only offers the business tax ID field for countries that have one, so it is not shown for US billing addresses.

Your address and tax ID appear on the invoice PDF. The online invoice page shows only the billing name, so download the PDF if you are checking the full details.

### How do I change my billing address or tax ID after upgrading?

Go to [Settings](https://biomni.phylo.bio/settings) → Billing → **Billing details**, then click **Update billing details**. This opens the Stripe billing portal, where you can change the billing name, address and tax ID. No support request is needed.

On a Team plan, only workspace admins and owners can view or change billing details. Other members do not see them at all — ask an admin on your workspace.

### Can you correct an invoice I have already received?

No. Changes apply to invoices issued from that point on — Stripe copies your details onto an invoice when it is issued, so an invoice that already exists keeps what it was issued with and cannot be reissued. Set your billing name, address and tax ID before your next invoice is due.

### Can I change the email address invoices are sent to?

Yes. The same **Update billing details** button lets you change the billing email, which is useful for sending invoices to accounts payable rather than to whoever signed up. This is separate from the email you log in with, and changing your login email will not overwrite it.


# Quickstart
Source: https://docs.biomni.phylo.bio/quickstart

Create a task, add your data, and work with Biomni's results

This guide takes you from a blank task to a result you can inspect and refine.

## 1. Choose where the work belongs

Use **Quick Tasks** for a one-off question. For an ongoing experiment or dataset,
create a project so its tasks can share files and project context.

To create a project, open the project selector in the sidebar and select
**Create a new project**. Give it a clear name; you can add context,
instructions, and auto attached Skills later under **Settings → Projects**.

## 2. Create a task

Open the project and create a new task. A task is one conversation with Biomni.
Keep a task focused on one analysis thread so its files, decisions, and follow-up
requests remain easy to understand.

If the model selector is available, **Standard** is the default for everyday
work. See [Models & Compute](/features/models-and-compute) before choosing Fast,
Max, or a custom model.

## 3. Add files, resources, and Skills

Select **+ Add** beside the composer to open the current attachment menu:

* **Upload files** or **Upload folder** adds local data.
* **Select from uploaded files** attaches an existing project file.
* **Import from cloud storage** copies supported external files into the
  project when that feature is enabled.
* **Draw molecule** draws a structure and attaches it as a SMILES file, when
  that feature is enabled. See [Chemical Structures](/features/chemical-structures).
* **Resources** opens databases, scientific tools, and software. You can also
  type `@` to search resources and files.
* **Skills** opens reusable workflows. You can also type `+` to search Skills.
* **Connectors** exposes connected external services when your organization has
  enabled them.

Selected files, Skills, and resources appear directly in the message so you can
confirm the task has the right context before sending.

> [!TIP]
>
> For a folder with many related files, upload the folder or a ZIP instead of
> attaching files one by one. A single message can attach up to 100 files.

## 4. Write the request

Include four things:

1. **Goal** — the decision, analysis, or artifact you need.
2. **Inputs** — filenames, cohorts, organisms, conditions, or sources.
3. **Constraints** — required method, reference build, thresholds, or exclusions.
4. **Output** — the files, figures, tables, or explanation you expect.

```text theme={null}
Compare treatment and control in @counts.csv using the sample labels in
@metadata.csv. Run differential expression with an adjusted p-value cutoff of
0.05. Return a CSV of all results, a labeled volcano plot, and a short methods
summary that states every filtering decision.
```

See [How to Prompt](/how-to-prompt) for more patterns.

## 5. Follow the work

After you send the message, the task shows the agent's progress and tool
activity. Expand trace sections when you need to inspect commands, tool inputs,
or outputs.

Depending on the work, the task can also show:

* a **Plan** for multi-step execution;
* **Results** generated during the task;
* **Compute** or HPC activity that continues in the background; and
* **Notes** associated with the task.

You can leave a long-running task and work elsewhere. Return from the project
sidebar to check its current status.

## 6. Inspect the result

Generated files appear as artifacts in the conversation and in **Results**.
Open a supported file to preview it, or download it for local inspection. Keep
the analysis in the same task when asking Biomni to revise an existing result:

```text theme={null}
Regenerate the volcano plot with larger labels and annotate the ten genes with
the smallest adjusted p-values. Keep the underlying result table unchanged.
```

## 7. Verify important work

* Open citations and confirm that they support the nearby claim.
* Inspect generated tables, notebooks, plots, and reports.
* Ask Biomni to state assumptions, exclusions, software versions, and parameters.
* Run [Scientific Review](/features/scientific-review) on a completed answer.
* Independently validate results used for clinical, regulatory, or publication
  decisions.

## Next steps

> [card] [Projects & Drive](/features/projects-and-drive)
>
> Organize tasks, files, and project settings.

> [card] [Skills](/features/skills-and-capabilities)
>
> Attach a reusable scientific workflow.

> [card] [Cloud Storage](/features/cloud-storage)
>
> Import external files from a connected source or public link.

> [card] [Get support](/support/customer-support)
>
> Contact the team or open the in-product help menu.


# Report a Bug
Source: https://docs.biomni.phylo.bio/support/bug-reporting

Send the details the Biomni team needs to investigate a product issue

For self-serve Biomni Lab, the fastest reporting flow is built into the product:

1. Select **Help** in the sidebar.
2. Choose **Report a Bug**.
3. Describe the problem and submit the report.

If **Report a Bug** is not present, use **Live Chat** or email support.

## What to include

* what you were trying to do;
* what happened and what you expected instead;
* steps that reproduce the issue;
* the affected task or project;
* the approximate time and your time zone;
* the browser or client you were using; and
* a screenshot or screen recording when it helps explain the behavior.

For an incorrect scientific result, also identify the input file, disputed
claim or output, and the evidence you expected Biomni to use.

## Protect sensitive information

Do not paste passwords, API keys, access tokens, private keys, or credentials
into a report. Avoid adding regulated or sensitive source data unless the
approved support process for your organization explicitly permits it.

## Other support channels

> [card] [Customer support](/support/customer-support)
>
> Live Chat, email, and workspace-specific support.

> [card] [Biomni community](https://join.slack.com/t/biomnigroup/shared_invite/zt-478z7aarm-~JC0jFpGZZorug6FhcuZFA)
>
> Discuss product usage with other researchers.


# Customer Support
Source: https://docs.biomni.phylo.bio/support/customer-support

Get product, account, billing, or technical help

Select **Help** in the Biomni Lab sidebar to see the support options available
for your workspace.

## Live Chat

Choose **Help → Live Chat** for product and technical questions. Include the
affected task, the approximate time of the issue, and what you expected to
happen.

## Email

> [card] [Email Phylo Support](mailto:support@phylo.bio)
>
> [support@phylo.bio](mailto:support@phylo.bio)

Email is useful for account, billing, access, and longer support requests. Do not
send passwords, API keys, tokens, or private keys.

## Community Slack

The public Biomni Lab community is available on self-serve workspaces through
**Help → Join Slack**.

> [card] [Join the Biomni community](https://join.slack.com/t/biomnigroup/shared_invite/zt-478z7aarm-~JC0jFpGZZorug6FhcuZFA)
>
> Ask usage questions and learn from other researchers.

## Before contacting support

1. Check the task status and expand the relevant error or tool trace.
2. Retry only if doing so cannot duplicate an external write or expensive job.
3. Record the task, time, client, and steps that led to the problem.
4. Use [Report a Bug](/support/bug-reporting) for reproducible product defects.

We can help with account setup, product usage, unexpected behavior, analysis
workflow questions, billing, and workspace administration.


# Refund Policy
Source: https://docs.biomni.phylo.bio/support/refund-policy

When paid Biomni Lab plans qualify for a refund and how to request one

**Effective date:** September 30, 2026

This policy applies to paid Biomni Lab self-serve plans purchased through Phylo (including Pro, Team, monthly, annual, and academic-discounted plans). Enterprise, pilot, SOW, invoice, PO, or custom-contract customers are governed by the terms in their signed agreement.

## Cancellation

* You can cancel a self-serve subscription at any time from **Settings → Usage & Billing**.
* Cancellation stops future renewals. Unless a refund is approved under this policy, you will keep access to the paid plan through the end of the current billing period.
* We do not automatically prorate mid-cycle cancellations.
* Please double check that you have cancelled your subscription before reaching out to our team to process a refund according to the qualifications below.

## Refund Guidelines

We may provide a full refund for the current billing period when **all** of the following are true:

1. **Timely request.** The refund request was submitted within **3 days** of the payment for a monthly plan or within **14 days** for an annual plan. Eligibility is based on the time the request is received, even if Support reviews it after the applicable window has closed.
2. **Minimal usage.** Since the charge, the account has had minimal use of Biomni Lab. Refund eligibility is determined at Phylo’s discretion based on agent runs, task and workflow execution, credit consumption, paid compute, HPC, and other metered platform resources.
3. **Good standing.** The account is not suspended, terminated, or under review for a Terms of Service, abuse, security, fraud, or payment violation.
4. **First refund for the period.** The request is not a repeated refund request for the same subscription period or a pattern of subscribe-use-refund behavior.

## Billing Errors

We may refund or correct charges caused by **billing mistakes**, including:

* You received a duplicate charge for the same subscription or transaction;
* You were charged the wrong amount;
* You were charged after a confirmed cancellation;
* You were charged for the wrong plan or billing interval;
* You were charged under the wrong academic/non-academic price when you were eligible for the academic discount at the time of purchase.

If the issue is an academic discount or institution eligibility problem, please contact [support@phylo.bio](mailto:support@phylo.bio) with the email address and institution that should be associated with the account.

## Service Issues

Because Biomni Lab usage can involve agentic workflows, model calls, credit consumption, compute, and long-running tasks, refunds for service issues are reviewed case by case.

We may provide a refund, partial refund, or service credit when:

* A sustained Phylo-side outage or platform defect prevented normal use of the paid plan;
* A billing or usage-metering issue incorrectly consumed credits or blocked access;

We generally do **not** provide refunds for:

* Expected variability in AI-generated outputs;
* User errors, incorrect prompts, or unsuitable uploaded data;
* Normal queueing, rate limits, or usage limits disclosed in the product;
* Dissatisfaction after substantial credit, compute, or task usage;
* Third-party model or infrastructure behavior outside Phylo’s reasonable control, unless it caused a material Phylo-side service failure.

## Team Plans

For Team plans:

* Refund eligibility is based on usage across the entire workspace or team, not only the billing admin’s account.
* If any team member has materially used paid credits, tasks, agents, compute, or other paid resources during the billing period, the plan may no longer qualify for a full refund.
* Seat additions, upgrades, or plan changes may be refunded or credited if requested promptly and there was little or no usage associated with the added seats or upgraded entitlement.

## Enterprise, Invoice, PO, and Custom Agreements

Enterprise, pilot, invoice, purchase-order, prepaid-credit, committed-usage, single-tenant, or custom-deployment customers are handled under the applicable signed order form, MSA, SOW, or other written agreement.

Unless the agreement says otherwise:

* Implementation fees, onboarding fees, prepaid credits, committed usage, and custom deployment fees are non-refundable;
* Unused committed credits are not automatically refundable;
* Service credits, rollovers, or other remedies may be offered according to the contract or at Phylo’s discretion.

## How to Request a Refund

To request a refund, contact Phylo Support ([support@phylo.bio](mailto:support@phylo.bio)) with:

* The email address associated with the account, or the admin email for a Team plan;
* The charge date and amount;
* A brief explanation of the request;
* Confirmation of whether the plan has been used since the charge; and
* Any supporting screenshots, invoices, or cancellation confirmations.

Approved refunds are returned to the original payment method. Processing times vary by payment provider and bank and may take several business days.

## Phylo’s Discretion

Phylo may approve, deny, partially approve, or provide service credit for refund requests based on account history, usage, billing records, service availability, and the specific circumstances of the request. This policy is intended to be fair to customers while accounting for the real costs of agent runs, credits, compute, and other platform resources consumed through Biomni Lab.


# Verifying AI-Generated Content
Source: https://docs.biomni.phylo.bio/support/verifying-ai-generated-content

How to check whether content came from Biomni, using free tools

Biomni is an AI system. Its responses, reports, figures, and code are generated
by AI models. On deployments that enable EU AI Act transparency controls,
Biomni also marks this output in machine-readable ways. This page explains
those markers and how anyone can check for them, free of charge.

> [!NOTE]
>
> These markers are enabled per deployment. If you are unsure whether your
> workspace has them, ask your administrator or
> [contact support](/support/customer-support).

## What Biomni marks

| Where the content is | Marker | How to check |
| - | - | - |
| Results copied to My Drive or a Project Drive, and images Biomni generates | Object metadata `ai-generated: true` and `generator: biomni`, plus `task-id` and `model-id` where known | The response headers when downloading the file from Biomni: `x-amz-meta-ai-generated`, `x-amz-meta-generator` |
| Results downloaded as a ZIP | Response headers `X-AI-Generated: true` and `X-AI-Generator: biomni` | Your browser's network inspector while downloading |
| Messages and result listings from the Biomni API and MCP server | An `ai_disclosure` object: `{"is_ai_generated": true, "generator": "biomni", ...}` | Read the field in the JSON response. See the [API quickstart](/api/quickstart). |
| Shared session links | A top-level `ai_disclosure` object on the replay payload (no task or model identifiers) | Read the field in the JSON response |
| Generated images | C2PA Content Credentials embedded by the image model provider, which Biomni stores unchanged | [Content Credentials Verify](https://contentcredentials.org/verify) or `c2patool <file>` |
| Text written by Claude models | An imperceptible watermark applied by Anthropic | Anthropic has announced a detection tool but has not released it publicly yet |

## Checking a download

The labels are HTTP response headers, so check them while downloading from
Biomni. For a file download link, this fetches the file (GET), prints the
headers, and discards the body:

```bash theme={null}
# Replace the URL with a download link from Biomni.
curl -s -D - -o /dev/null "<download-url>" | grep -i -E "x-amz-meta-ai-generated|x-ai-generated|x-amz-meta-generator"
```

For a ZIP downloaded while signed in, use your browser's network inspector and
look at the download request's response headers.

For an image, upload it to [contentcredentials.org/verify](https://contentcredentials.org/verify)
or run the open-source [`c2patool`](https://github.com/contentauth/c2pa-rs/tree/main/cli):

```bash theme={null}
c2patool figure.png
```

## Limits

* File labels and download headers exist only on the response from Biomni.
  They are not written into the file, so a saved copy, even an unchanged one,
  does not carry them.
* Marks embedded in the content (C2PA in images, text watermarks) travel with
  it, but re-saving, converting, screenshotting, or copying text into another
  document can remove them.
* Text watermarks may not survive heavy editing, paraphrasing, or translation.
  A missing marker does not prove that content was written by a person.
* Files you upload yourself are never marked.