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.

Collecting a cohort

Results are paged, and the page size is capped (the cap depends on your tier and the entity). To get a whole cohort in one array, use --all:

gosset trials --target TL1A --all > trials.json

It pages until the set is exhausted, picks a stable sort so no record is served twice or skipped, and deduplicates on the entity id. Progress goes to stderr, so > file.json stays clean.

It refuses above 10,000 rows rather than walking the corpus — narrow the query with filters. If you pass your own --sort, that ordering is used instead; the command then tells you on stderr if the pull came back short.

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.

Agent skills

Discover reusable workflows and load one into your AI agent:

gosset skills
gosset skills competitive-landscape
gosset skills competitive-landscape > competitive-landscape.md

competitive-landscape is free for everyone. Both commands work offline without signing in. The named command prints the full Markdown skill for an agent to follow; it does not launch a model or run the research itself. Ask your agent to use it for a target, for example: “Use this skill to build a TL1A landscape.”

The workflow covers a developer/phase bullseye, asset tables, indication coverage, trial and deal activity, advanced-program deal histories, and data exports, following the TL1A session. Running data queries requires normal Gosset authentication and remains subject to account limits.

Use gosset skills --json for the catalog or gosset skills competitive-landscape --json for metadata and skill content. More skills are coming; subscribe to Gosset for more.