Gosset

Command-line and programmatic access to Gosset's database of 100,000+ drug assets — drugs, clinical trials, companies, deals and news.

The CLI is the main interface. Search from your terminal, pipe into jq, or hand it to an agent. The Python SDK is there when you need programmatic control.

pip install gosset
gosset auth                           # one-time browser sign-in
gosset drugs --target PD-1 --phase 3

Quickstart

1. Install

pip install gosset

Python 3.9+. For AI-agent support: pip install "gosset[agents]".

2. Authenticate

gosset auth                           # opens a browser, stores your key

That is the whole of it. The key is saved to ~/.config/gosset/credentials (mode 0600) and picked up by every later command, in this shell and in new ones — there is nothing to export and nothing to add to a shell profile.

gosset auth --status                  # signed in? which key? from where?
gosset auth --logout                  # remove the stored key

Or non-interactively, if you already have a key:

export GOSSET_API_KEY='your_key_here'

3. Ask it something

gosset drugs "pembrolizumab"

That's it. Output is JSON by default.

CLI

The idea: pass names, not ids

Every filter accepts a name or an id. The CLI resolves names to ids for you, so you never handle raw ObjectIds.

gosset drugs --target PD-1            # "PD-1" is resolved for you
gosset trials --disease "atopic dermatitis"
gosset deals --buyer Merck

Add --debug to see the resolved request that was actually sent.

Five entity commands

# Drugs — positional NAME, resolved to an id
gosset drugs "pembrolizumab"
gosset drugs --target PD-1 --phase 3 --limit 20
gosset drugs --disease "non-small cell lung cancer" --modality antibody --industry-only

# Trials — positional SEARCH takes an NCT id, acronym, or title text
gosset trials NCT05599191
gosset trials "semaglutide phase 3"
gosset trials --drug semaglutide --phase 3 --status recruiting --has-results

# Companies — positional NAME, resolved to an id
gosset companies "Merck"
gosset companies --disease oncology --country US --public

# Deals — filters only, no positional
gosset deals --drug pembrolizumab --since 2024-01-01
gosset deals --buyer Merck --deal-type acquisition --min-value 1000

# News — positional SEARCH is free text
gosset news "GLP-1"
gosset news --disease "atopic dermatitis" --since 2025-01-01

Two prediction commands

gosset ptrs NCT05599191               # probability of technical & regulatory success
gosset timeline NCT05599191           # predicted primary-completion date
gosset timeline NCT05599191 --as-of 2025-06-01   # point-in-time, no lookahead

Schemas

Every entity returns a documented set of fields. gosset schema <entity> prints the contract:

gosset schema            # all entities
gosset schema drugs      # field list with descriptions

The schema is defined and applied server-side — gosset schema fetches it rather than shipping a copy that could drift. A drug publishes 76 documented fields; a trial 63.

Every record comes back on that one contract. There is no second shape to opt into, and nothing the CLI returns is outside the published field list.

gosset drugs keytruda                # the published schema
gosset drugs keytruda --include-ids  # add target_ids, disease_class_ids, ...

Flags every entity command shares

Per-command filters differ — gosset <command> --help lists them.

Built for pipes and agents

JSON on stdout by default, so it composes:

# Every phase-3 PD-1 asset, names only
gosset drugs --target PD-1 --phase 3 --fields name --limit 100 | jq -r '.[].name'

# Score every recruiting trial for a drug
gosset trials --drug semaglutide --status recruiting --fields nct_id \
  | jq -r '.[].nct_id' \
  | xargs -I{} gosset ptrs {}

Use --table when a human is reading:

gosset drugs --target PD-1 --phase 3 --table

SDK

When you need programmatic control, the same data is available from Python.

from gosset import GossetClient

client = GossetClient()                    # reads GOSSET_API_KEY

drugs = client.query("drugs", where={"field": "targets", "op": "eq", "value": "PD-1"})
trials = client.query("trials", where={"field": "main_drug", "op": "eq",
                                       "value": "semaglutide"})

ptrs = client.estimate_ptrs({"nct_id": "NCT05599191"})
print(ptrs["probability"])

Search

query() takes a predicate tree — {field, op, value} leaves combined with and / or / not — and resolves names to ids server-side, so you can pass "PD-1" or "semaglutide" rather than looking up an id first. The response has a resolved block showing what each name became.

Prediction

Resolution and schema

estimate_ptrs accepts either a trial ({"nct_id": ...}) or a described asset built from get_trial_params, so you can score hypothetical designs, not just registered trials.

Errors

from gosset import GossetClient, GossetAPIError

try:
    client.estimate_ptrs({"nct_id": "NCT00000000"})
except GossetAPIError as e:
    print(f"request failed: {e}")

Authentication

The CLI and SDK read the same credential, checked in this order:

1. --api-key (CLI) or GossetClient(api_key=...) (SDK)

2. GOSSET_API_KEY

3. GOSSET_OAUTH_TOKEN

4. the key stored by gosset auth (~/.config/gosset/credentials)

Environment beats the stored key, so GOSSET_API_KEY=... gosset drugs does what it looks like it does and CI is unaffected by whoever last ran auth.

Get a key with gosset auth, which opens a browser and stores it. For CI, where a file in a discarded container is no use, print the export line instead:

eval "$(gosset auth --print-export)"
# or, to capture just the value
export GOSSET_API_KEY="$(gosset auth --quiet)"

gosset get-token returns a raw OAuth token instead. That is what MCP clients need, and it is not accepted by this API — the REST endpoints validate bearers against your account's API key, so an OAuth token fails every call with "Authentication failed". Use gosset auth unless you specifically want the OAuth credential.

(gosset login and gosset get-key are aliases for gosset auth — the older name keeps working.)

Point at a different environment with --base-url or GOSSET_API_URL.

Links

• Documentation — https://docs.gosset.ai/cli/
• Homepage — https://gosset.ai
• Issues — https://github.com/gosset-ai/gosset/issues

License

Apache License 2.0 — see LICENSE.