Skip to content

Predictions: ptrs and timeline ​

Two models, each run on one trial by its ClinicalTrials.gov id.

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

bash
gosset ptrs <NCT_ID> [--model-version v3|v4-rc]

There are two models. V3 is the default.

V3 (default)V4 (--model-version v4-rc)
QuestionWill 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 fieldprobabilityprogression_score
Explanationparam_influence: the trial inputs that pushed the estimate up or downfeature_influence.contributions: the same idea, grouped by evidence type
ScopePhase 1 to 3. A Phase 4 trial is an errorIndustry-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 ​

bash
gosset ptrs NCT07012395 | jq '{probability, target_phase}'
json
{
  "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:

bash
gosset ptrs NCT07012395 | jq -r '.param_influence[:4][] | "\(.label)\t\(.influence)"'
Countries	-0.408071
FDA Designations	-0.324806
Diseases	-0.248749
Phase	-0.246897

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

bash
gosset ptrs NCT07012395 --model-version v4-rc \
  | jq '{status, progression_score, model_version, phase, reason}'
json
{
  "status": "ready",
  "progression_score": 0.22781767511736434,
  "model_version": "v4-rc.6",
  "phase": 2,
  "reason": null
}
bash
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.4492694468038093

Every V4 response also carries:

FieldMeaning
statusready (scored), pending (trial inputs still missing) or unsupported (outside the model's scope)
reasonWhy there is no score, for example unsupported_phase
prediction_horizon{"anchor": "primary_completion_date", "kind": "within_two_years"}
forecast_at, prediction_generated_atWhen the inputs were captured and the score computed
phase, highest_phase, phase_detailsThe phase the model used; 1b/2a keeps both parts
noticeA 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:

bash
gosset ptrs NCT03034096 --model-version v4-rc | jq '{status, reason, progression_score}'
json
{
  "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:

bash
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)')"
done
NCT07620392  ready 0.18743373970557836
NCT07223697  ready 0.20065331242524925
NCT07861074  ready 0.18163944109642527
NCT07697456  ready 0.21572551030401202
NCT07812116  ready 0.20040024328300216

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

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

bash
gosset timeline NCT05424835
json
{
  "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.

FieldMeaning
trial_statusrunning, not_started, completed, outside_coverage or not_found
expected_completion_dateThe model's central estimate
lower_bound_date, upper_bound_dateThe 80% range (also as …_days from as_of)
sponsor_estimated_completionThe date the sponsor registered
actual_completion_dateFilled in once the trial has completed
warningsReasons 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:

bash
gosset timeline NCT05599191 --as-of 2024-06-01 \
  | jq '{trial_status, expected_completion_date, upper_bound_date, actual_completion_date}'
json
{
  "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:

bash
gosset timeline NCT06651281 | jq '{trial_status, warnings}'
json
{
  "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.

Gosset Documentation