Analytics Data API

The full trial dataset as JSON, rebuilt nightly, with incremental updates. An add-on for Enterprise plans.

Overview

The feed is the full dataset: every approved study with its sponsor, cancers, drugs and approved sites. It is rebuilt nightly at about 06:00 UTC, so every request between rebuilds returns the same data. Your company's API add-on must be on; a company admin then generates the key from the API page on your company dashboard.

Request

Send a GET request to /api/v1/studies with your key as a bearer token. Responses are gzip-compressed JSON and are never cached.

curl --compressed -H "Authorization: Bearer $TT_API_KEY" \
  "https://www.theranostictrials.org/api/v1/studies?since=2026-11-01T06:00:00Z"

The optional since parameter takes a date (YYYY-MM-DD, midnight UTC) or an ISO-8601 datetime with Z or an offset. Without it you get every study.

Staying up to date

Store generatedAt from each response and pass it as since next time. Apply studies as upserts by id and delete removedIds. A response with since contains only studies that changed after that moment, plus removedIds for studies that are no longer published.

{
  "generatedAt": "2026-11-10T06:00:12.000Z",
  "since": "2026-11-01T06:00:00Z",
  "license": { "licensee": "Your Company", "terms": "Internal use per your agreement. Attribute TheranosticTrials.org in any publication or client material. Resale is not permitted." },
  "count": 1,
  "studies": [ { "id": "…", "nctNumber": "NCT00000000", "name": "…" } ],
  "removedIds": ["…"]
}

Study record

Each item in studies has these fields.

Study record fields
Field	Type	Notes
id	string	Stable study identifier.
nctNumber	string	ClinicalTrials.gov NCT number.
name	string	Study title.
status	string	Recruitment status.
phase	string \| null	Trial phase.
studyType	string \| null	Study type.
startDate	string \| null	YYYY-MM-DD.
endDate	string \| null	YYYY-MM-DD.
sponsor	{ id, name, type } \| null	Lead sponsor; type may be null.
cancers	{ id, name }[]	Cancers the study addresses, sorted by id.
stages	string[]	Disease stages.
drugs	{ compoundName, chelator, ligandClass, linker, isotopes, targets }[]	Each drug lists isotopes and targets as { id, name }[]; the other fields may be null.
sites	{ id, name, country }[]	Approved study sites.
url	string \| null	Public page on TheranosticTrials.org; null when the study has no cancer.
clinicalTrialsUrl	string	The study on ClinicalTrials.gov.

Errors

Errors are JSON of the form { "error": "…" }.

Error responses
Status	Message	Meaning
401	Missing API key	No Authorization: Bearer header.
401	Unknown API key	The key is not recognised.
403	API add-on is off	Your company does not have the API add-on.
403	Data access has ended	Your company's data access is no longer active.
403	Over seat limit — ask your admin to remove seats	Your company has more seats in use than its limit.
400	since must be a date (YYYY-MM-DD) or ISO-8601 datetime	The since parameter could not be parsed.
429	Rate limit exceeded	The daily limit is used up. Wait Retry-After seconds.
503	Snapshot not built yet	The first nightly snapshot does not exist yet.

Limits

Each company can make 24 successful pulls in any rolling 24 hours. Beyond that the API returns 429 with a Retry-After header, in seconds. Since the data changes once a night, one pull a day with since is normally enough.

Terms

Every response carries these terms in license.terms:

Internal use per your agreement. Attribute TheranosticTrials.org in any publication or client material. Resale is not permitted.