Predictions: ptrs and timeline
Two models, each run on one trial by its ClinicalTrials.gov id.
| Command | Predicts |
|---|---|
gosset ptrs NCT… | how likely the trial's program is to progress (V3 by default, V4 on request) |
gosset timeline NCT… | when the trial will reach primary completion, with a range |
Both count against your plan's monthly prediction allowance; see Quotas.
gosset ptrs: trial progression
gosset ptrs <NCT_ID> [--model-version v3|v4-rc]There are two models. V3 is the default.
| V3 (default) | V4 (--model-version v4-rc) | |
|---|---|---|
| Question | Will the program move from this trial's phase to the next one (Phase 3 trials: to registration)? | Will a higher-phase trial start within two years of this trial's primary completion? |
| Headline field | probability | progression_score |
| Explanation | param_influence: the trial inputs that pushed the estimate up or down | feature_influence.contributions: the same idea, grouped by evidence type |
| Scope | Phase 1 to 3. A Phase 4 trial is an error | Industry-sponsored or industry-collaborating trials, Phase 1 to 3 |
--model-version v4-rc selects the current V4 release, reported back as v4-rc.6. Passing v4-rc.6 explicitly gives the same model.
V3
gosset ptrs NCT07012395 | jq '{probability, target_phase}'{
"probability": 0.09768843393301452,
"target_phase": 3
}NCT07012395 is SKYLINE-UC, a Phase 2 platform trial in ulcerative colitis, so target_phase is 3. What moved the estimate:
gosset ptrs NCT07012395 | jq -r '.param_influence[:4][] | "\(.label)\t\(.influence)"'Countries -0.408071
FDA Designations -0.324806
Diseases -0.248749
Phase -0.246897Influences are on the log-odds scale: negative values lower the estimate.
The full response also has transitions (one entry per phase step, each with its own probability and influences), raw_probability and versions.
V4
gosset ptrs NCT07012395 --model-version v4-rc \
| jq '{status, progression_score, model_version, phase, reason}'{
"status": "ready",
"progression_score": 0.22781767511736434,
"model_version": "v4-rc.6",
"phase": 2,
"reason": null
}gosset ptrs NCT07012395 --model-version v4-rc \
| jq -r '.feature_influence.contributions[:4][] | "\(.label)\t\(.contribution)"'Investigational drugs -0.7300112303375937
Drug development history -0.5168025663415137
Genetic evidence 0.48423688066417425
Indication history 0.4492694468038093Every V4 response also carries:
| Field | Meaning |
|---|---|
status | ready (scored), pending (trial inputs still missing) or unsupported (outside the model's scope) |
reason | Why there is no score, for example unsupported_phase |
prediction_horizon | {"anchor": "primary_completion_date", "kind": "within_two_years"} |
forecast_at, prediction_generated_at | When the inputs were captured and the score computed |
phase, highest_phase, phase_details | The phase the model used; 1b/2a keeps both parts |
notice | A plain-language reminder of what the score is not |
Always check status before reading the score. A Phase 4 trial, for example, returns no score:
gosset ptrs NCT03034096 --model-version v4-rc | jq '{status, reason, progression_score}'{
"status": "unsupported",
"reason": "unsupported_phase",
"progression_score": null
}V4 was developed on trials with an industry sponsor or collaborator. A trial registered as having no industry involvement returns unsupported.
What these numbers are not
Neither score is a probability of regulatory approval or of meeting the endpoints. V3 estimates one phase step; V4 estimates whether a later-phase trial starts within two years. They answer different questions, so compare them with care. For an end-to-end approval estimate, combine the step you need with late-phase success rates from another source.
More than one NCT id
The CLI scores one trial per call. To score a list, loop over it:
for nct in $(gosset trials --target TL1A --phase 2 --industry-only --limit 5 --fields nct_id | jq -r '.[].nct_id'); do
echo "$nct $(gosset ptrs "$nct" --model-version v4-rc | jq -r '.status + " " + (.progression_score|tostring)')"
doneNCT07620392 ready 0.18743373970557836
NCT07223697 ready 0.20065331242524925
NCT07861074 ready 0.18163944109642527
NCT07697456 ready 0.21572551030401202
NCT07812116 ready 0.20040024328300216Each call counts against your prediction allowance.
Scoring a design that isn't registered yet, changing one input of a registered trial, choosing the disease ontology, program-level estimates, historical benchmarks and similar-trial search are in the Python SDK, not the CLI.
gosset timeline: predicted primary completion
gosset timeline <NCT_ID> [--as-of YYYY-MM-DD]Predicts when a running trial will reach primary completion, with an 80% range, next to the sponsor's own estimate.
gosset timeline NCT05424835{
"nct_id": "NCT05424835",
"as_of": "2026-11-16",
"trial_status": "running",
"elapsed_days": 1565,
"expected_completion_date": "2027-04-07",
"expected_remaining_days": 142,
"lower_bound_date": "2027-01-07",
"upper_bound_date": "2029-02-23",
"sponsor_estimated_completion": "2026-12-31",
"sponsor_estimate_in_past": false,
"model_version": "remaining_time_v1",
"warnings": ["trial is more than 50% past its sponsor-planned completion date", "…"]
}NCT05424835 is a Phase 3 trial of trastuzumab rezetecan (SHR-A1811) in HER2+ metastatic breast cancer. The sponsor says December 2026; the model expects April 2027, with a range up to February 2029.
| Field | Meaning |
|---|---|
trial_status | running, not_started, completed, outside_coverage or not_found |
expected_completion_date | The model's central estimate |
lower_bound_date, upper_bound_date | The 80% range (also as …_days from as_of) |
sponsor_estimated_completion | The date the sponsor registered |
actual_completion_date | Filled in once the trial has completed |
warnings | Reasons to trust the estimate less, such as limited history for the trial |
Backtests with --as-of
--as-of asks for the prediction the model would have made on that date, using only what was known then:
gosset timeline NCT05599191 --as-of 2024-06-01 \
| jq '{trial_status, expected_completion_date, upper_bound_date, actual_completion_date}'{
"trial_status": "running",
"expected_completion_date": "2024-09-08",
"upper_bound_date": "2024-11-18",
"actual_completion_date": "2025-12-17"
}Here the trial finished later than the model's whole range, which is the kind of check a backtest is for.
When there is no prediction
The model covers trials it has registry history for. For others it returns trial_status: "outside_coverage" and no dates; this is common for recently registered trials. An id that isn't a known trial is an error:
gosset timeline NCT06651281 | jq '{trial_status, warnings}'{
"trial_status": "outside_coverage",
"warnings": ["no timeline available: trial outside model coverage"]
}Quotas
Predictions are counted per call against a rolling 30-day allowance for your account, shared by the CLI, the API and the MCP server. gosset usage shows how many you've used under "Monthly allowance (last 30 days)", as calls used out of your limit, or "unlimited on your account".
When the allowance is used up, the call fails with exit code 1 and the API's explanation on stderr (HTTP 429). Retrying doesn't reset a 30-day window. In the Python SDK the same error is a GossetAPIError with status_code 429 and the details (reason, limit, window) in .details. See Usage & limits.