Skip to content

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}/query

The 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:

bash
gosset companies --where asset.target=TL1A --where asset.phase=3 --fields name,category --table
name                                 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 Pharma

Put alternatives inside one --where, separated by |, for OR:

bash
gosset drugs --target TL1A --where 'developer.country=China | developer.country=Japan' \
  --limit 5 --fields name,phase,developers --table

Together these give "A and (B or C)", which the named flags can't express:

bash
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 ​

WriteMeaning
field=valueequals
field=a,bequals any of a, b
field~textcontains text (free-text fields such as search)
field!=valuedoes not equal
field!~textdoes 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).

EntityNames or idsOther filters
drugsname, drug, target, target_class, disease, modality, companyphase, 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
trialsdrug, target, target_class, disease, sponsorsearch, 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
companiesname, company, disease, modalitycountry, type, stage, public
dealsdrug, target, disease, modality, buyer, sellerdeal_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
newsdrug, disease, companysearch, category, source_type, since, until
abstractsdrug, disease, target, target_class, modality, company, developersearch, 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_valency on drugs Added 16 November 2026. Filter vaccines with --where vaccine_pathogen or vaccine_valency.. See Vaccines.
  • prior_therapy_classes on 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_setting on trials Added 12 November 2026. Filter trials by stage, severity or treatment setting at entry..
  • accelerated_approval, accelerated_approval_overdue on 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_naive on trials Added 6 November 2026. Filter trials by ECOG limit, required prior lines or treatment-naive population..
  • primary_completion_since, primary_completion_until, endpoint_categories on trials Added 26 October 2026. Filter trials by primary completion date or endpoint category..
  • source_type on news Added 1 November 2026. Filter news by source type, such as press release or SEC filing..
  • source_verified, provenance_status, include_hidden on 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:

  • target matches the target and its ontology class. On trials it matches a target on any arm.
  • target_class matches only the ontology class of the drug's primary target, and includes child classes. IL-23 then also returns the p40 antibody ustekinumab and the p19 antibodies risankizumab and guselkumab.
bash
gosset trials --where target_class=IL-23 --phase 3 --limit 5 --fields nct_id,drug --table

A dotted name reaches into a related record:

FromRelationSub-fields
drugsdeveloper, trialdeveloper: public, stage, type, country, funding_min; trial: phase, status, registry, progressed, disease, target
trialsdrug, sponsordrug: modality, target, target_class, disease, phase; sponsor: as developer
companiesasset, trialas the drug and trial sub-fields above
dealsbuyer, seller, drugbuyer and seller: as developer; drug: as above, except phase
bash
# 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 --table

What 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:

bash
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"]}'
json
{
  "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:

json
"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 ​

jsonc
{
  "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:

ShapeMeaning
{"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 ​

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 1A

Caveats ​

  • OR totals can be a lower bound. An or across fields runs each branch and merges them. If a branch hits the row cap, the response has a note and total is a minimum. Narrow the branch, or page.
  • total can be an estimate. total_is_exact: false in the response says so. Trials may report -1 when no exact count was computed.

Gosset Documentation