Query API and --where
Every entity command builds one query object and sends it to:
POST https://api.gosset.ai/v3/{drugs|trials|companies|deals|news|abstracts}/queryThe named flags (--target, --phase, …) cover the common filters. --where covers the rest, including conditions on related records. This page shows both, and how to send the same query from Python or curl.
Filtering with --where
One condition per --where. Repeat the flag to combine conditions with AND:
gosset companies --where asset.target=TL1A --where asset.phase=3 --fields name,category --tablename category
----------------------------------- ------------------------------------------------------------
Roche Pharma, Molecular Diagnostics, Protein Biomarker Diagnostics
Sanofi Pharma, Big Pharma
Roivant Sciences Biotech
Merck & Co. Pharma, Big Pharma
Pfizer Pharma, Big Pharma
Teva Pharmaceutical Industries Ltd. Biotech, Big PharmaPut alternatives inside one --where, separated by |, for OR:
gosset drugs --target TL1A --where 'developer.country=China | developer.country=Japan' \
--limit 5 --fields name,phase,developers --tableTogether these give "A and (B or C)", which the named flags can't express:
gosset trials --target TL1A --phase 2,3 --where 'sponsor.type=Big Pharma | sponsor.type=Biotech' \
--fields nct_id,phase,drug --table--where conditions are combined with the named flags using AND.
Operators
| Write | Meaning |
|---|---|
field=value | equals |
field=a,b | equals any of a, b |
field~text | contains text (free-text fields such as search) |
field!=value | does not equal |
field!~text | does not contain |
true and false are sent as booleans, so developer.public=false means "private developer". Quote the whole condition when it contains spaces, |, ! or &: --where 'company_type!=Big Pharma'.
There is no >, >=, < or <=. Ranges are named fields instead: since=, until=, approved_since=, min_value=, funding_min=. The CLI refuses a comparison and tells you which field to use:
$ gosset drugs --where 'funding>=100'
{"error": "'>=' is not supported — the API has no comparison operators. Ranges are named fields: use funding_min=, since=, approved_since="}Negation is limited
!= and !~ work only on fields that have an exclude rule, today company_type on drugs. On other fields the API refuses the query (HTTP 501), which the CLI currently reports as "The service is temporarily unavailable". Use a positive list instead, for example --phase 2,3 rather than phase!=1.
Fields you can filter on
Field names on this list are filter names. They are close to, but not always the same as, the field names in the results (see gosset schema).
| Entity | Names or ids | Other filters |
|---|---|---|
drugs | name, drug, target, target_class, disease, modality, company | phase, max_phase, route, action, effect, line, company_type, approved_since, accelerated_approval, accelerated_approval_overdue, combination, exclude_flags, industry_only, include_flagged_targets, adc_payload, adc_payload_axis, adc_linker, payload_mechanism_targets, vaccine_pathogen, vaccine_valency |
trials | drug, target, target_class, disease, sponsor | search, phase, status, registry, since, until, primary_completion_since, primary_completion_until, endpoint_categories, include_secondary_endpoints, composite_primary, composite_families, include_tte_oncology, industry_only, has_results, progressed, max_ecog_min, max_ecog_max, prior_lines_min, prior_lines_max, treatment_naive, stage_group, severity, treatment_setting, prior_therapy_classes |
companies | name, company, disease, modality | country, type, stage, public |
deals | drug, target, disease, modality, buyer, seller | deal_type, since, until, min_value, buyer_country, seller_country, buyer_public, seller_public, buyer_funding_min, seller_funding_min, drug_phase, source_verified, provenance_status, include_hidden |
news | drug, disease, company | search, category, source_type, since, until |
abstracts | drug, disease, target, target_class, modality, company, developer | search, conference, conference_year, trial, trial_link_source, annotation_level, latest_phase, is_drug, impact_min, impact_max, since, until |
Recently added --where filters:
vaccine_pathogen,vaccine_valencyon drugs Added 16 November 2026. Filter vaccines with --where vaccine_pathogen or vaccine_valency.. See Vaccines.prior_therapy_classeson trials Added 16 November 2026. Filter trials by required prior therapy with --where prior_therapy_classes.. See Line of treatment and population.stage_group,severity,treatment_settingon trials Added 12 November 2026. Filter trials by stage, severity or treatment setting at entry..accelerated_approval,accelerated_approval_overdueon drugs Added 6 November 2026. Filter drugs by FDA accelerated approval status..max_ecog_min,max_ecog_max,prior_lines_min,prior_lines_max,treatment_naiveon trials Added 6 November 2026. Filter trials by ECOG limit, required prior lines or treatment-naive population..primary_completion_since,primary_completion_until,endpoint_categorieson trials Added 26 October 2026. Filter trials by primary completion date or endpoint category..source_typeon news Added 1 November 2026. Filter news by source type, such as press release or SEC filing..source_verified,provenance_status,include_hiddenon deals Added 29 October 2026. Filter deals by whether a primary document backs them..
An unknown filter name is an error that lists the valid ones, so you can't misspell your way to an unfiltered result.
target and target_class
A target name can mean two things, so drugs, trials and abstracts take both:
targetmatches the target and its ontology class. On trials it matches a target on any arm.target_classmatches only the ontology class of the drug's primary target, and includes child classes.IL-23then also returns the p40 antibody ustekinumab and the p19 antibodies risankizumab and guselkumab.
gosset trials --where target_class=IL-23 --phase 3 --limit 5 --fields nct_id,drug --tableConditions on related records
A dotted name reaches into a related record:
| From | Relation | Sub-fields |
|---|---|---|
drugs | developer, trial | developer: public, stage, type, country, funding_min; trial: phase, status, registry, progressed, disease, target |
trials | drug, sponsor | drug: modality, target, target_class, disease, phase; sponsor: as developer |
companies | asset, trial | as the drug and trial sub-fields above |
deals | buyer, seller, drug | buyer and seller: as developer; drug: as above, except phase |
# Japanese companies running Phase 3 trials of small molecules
gosset companies --country Japan --where trial.phase=3 \
--where "trial.drug.modality=Small Molecules" --limit 3 --fields name --table
# TL1A drugs from developers that raised at least $100M
gosset drugs --target TL1A --where developer.funding_min=100000000 --fields name,developers --tableWhat a name matched
The CLI prints only the results. The API response also has a resolved block that says what each name became. Use the Python SDK or curl to see it:
curl -s -X POST https://api.gosset.ai/v3/drugs/query \
-H "Authorization: Bearer $GOSSET_API_KEY" -H "Content-Type: application/json" \
-d '{"where": {"field": "target", "value": "TL1A"}, "limit": 3, "fields": ["name", "phase"]}'{
"total": 88,
"results": [
{"name": "afimkibart", "phase": "3"},
{"name": "duvakitug", "phase": "3"},
{"name": "tulisokibart", "phase": "3"}
],
"resolved": {
"target": {
"input": ["TL1A"],
"matched": [{"as": "ontology_class", "class_ids": ["GT-22-03"], "ids": 18,
"name": "TNF-like cytokine 1A", "token": "TL1A"}],
"candidates": []
}
}
}matched shows the entity or class the name became and how many records it covers. candidates lists near misses, so you can see, for example, which of several companies a short name picked:
"company": {"input": ["Daiichi Sankyo"],
"matched": [{"as": "autocomplete", "ids": 1, "name": "Daiichi Sankyo"}],
"candidates": ["Daiichi Sankyo Co., Ltd.", "Daiichi Sankyo Healthcare", "Daiichi Sankyo Korea"]}The CLI total above is 75, not 88: gosset drugs adds exclude_flags=is_combination to hide trial-arm regimens.
Unresolved names never widen the query
If a name matches nothing, the response is empty with a message such as could not resolve 'notarealtarget' (target). A filter is never dropped. The CLI prints the message on stderr and exits with code 2.
The query object
{
"where": {"field": "target", "op": "is", "value": "TL1A"}, // a condition or a tree
"sort": "-phase", // optional; a published field, "-" for descending
"limit": 25, // page size, capped by your plan
"offset": 0,
"fields": ["name", "phase"], // optional; published field names
"include_ids": false // optional; add id fields for joins
}where is one of:
| Shape | Meaning |
|---|---|
{"field": …, "op": …, "value": …} | one condition |
{"and": [ … ]} | all must match |
{"or": [ … ]} | any may match |
{"not": … } | negation, where supported (see above) |
op is is (the default), in (a list) or contains (free text). A value can be a list, which means "any of".
gosset <entity> --debug prints the object the CLI sent, which is a quick way to turn a CLI command into an API call.
From Python
from gosset import GossetClient
client = GossetClient() # uses the key from `gosset auth` or GOSSET_API_KEY
res = client.query(
"drugs",
where={"and": [
{"field": "target", "value": "TL1A"},
{"field": "phase", "value": "3"},
]},
fields=["name", "phase", "developers"],
)
print(res["total"], [r["name"] for r in res["results"]])
# 3 ['afimkibart', 'duvakitug', 'tulisokibart']
print(res["resolved"]["target"]["matched"][0]["name"])
# TNF-like cytokine 1ACaveats
- OR totals can be a lower bound. An
oracross fields runs each branch and merges them. If a branch hits the row cap, the response has anoteandtotalis a minimum. Narrow the branch, or page. totalcan be an estimate.total_is_exact: falsein the response says so. Trials may report-1when no exact count was computed.