临床试验
概览
每一项登记的临床试验——设计、分组、入排、结局——一个 NCT 一条文档。
- 状态
- live
- 文档 id
nct_id如NCT02082496- 引用格式
[NCT02082496]- 更新于
- 2026-10
常用调用
找试验
POST /v1/trials/search {"query": "GLP-1 用于肥胖的三期试验", "filters": {"phase": "PHASE3", "overall_status": "RECRUITING"}}读一项
GET /v1/trials/read/NCT02082496 → 默认 level=detail：入排、终点、生物标志物、国家与中心数看某个字段有哪些值
GET /v1/trials/facets?field=phase → 带真实计数细则
- 按适应症筛用 condition_mesh（规范词）；conditions 是登记者自由填写的原文。
- 入排要点、生物标志物、既往治疗、ECOG 是模型从 eligibility 原文抽的，报名前请回原记录核对。
- overall_status=UNKNOWN 有 9.7 万项：登记者长期未更新，不代表试验已结束。
- 检索库里没有正文：level=full 暂不可用（登记记录全文（含各节原文）在 NAS ctgov/bulk，未进检索库）。
检索
POST
/v1/trials/search混合检索，每条命中一张卡片。2 credits。免费样例：
glp-1 obesity phase 3。过滤字段
| 字段 | 类型 · op | 含义 |
|---|---|---|
| phase | keyword · eq anyEARLY_PHASE1 · PHASE1 · PHASE2 · PHASE3 · PHASE4 · NA | 分期 |
| overall_status | keyword · eq anyRECRUITING · NOT_YET_RECRUITING · ACTIVE_NOT_RECRUITING · ENROLLING_BY_INVITATION · COMPLETED · TERMINATED · WITHDRAWN · SUSPENDED · UNKNOWN | 当前状态 |
| study_type | keyword · eq anyINTERVENTIONAL · OBSERVATIONAL · EXPANDED_ACCESS | 研究类型 |
| intervention_type | keyword · eq anyDRUG · BIOLOGICAL · DEVICE · PROCEDURE · BEHAVIORAL · DIAGNOSTIC_TEST …共 11 个，/facets 可列全 | 干预类型 |
| condition_mesh | keyword · eq any | 适应症 MeSH 词（规范词，比自由文本的 conditions 可靠） |
| countries | keyword · eq any | 试验国家 |
| start_year | integer · eq range | 开始年份区间 |
| has_results | bool · eq | 是否已登记结果 |
| sponsor_class | keyword · eq anyINDUSTRY · NIH · FED · OTHER_GOV · NETWORK · INDIV · OTHER | 申办方类型 |
还有 10 个，照样能用
| 字段 | 类型 · op | 含义 |
|---|---|---|
| sex | keyword · eqALL · FEMALE · MALE | 性别要求 |
| sponsor | keyword · eq any | 申办方名称（精确） |
| intervention_mesh | keyword · eq any | 干预 MeSH 词 |
| biomarker_names | keyword · eq any | 入排里提到的生物标志物（模型抽取） |
| performance_status | keyword · eq any | 体力状态要求，如 ECOG 0-1（模型抽取） |
| treatment_naive | bool · eq | 是否要求未经治疗（模型抽取） |
| enrollment | integer · eq range | 入组人数区间 |
| age_min_years | integer · eq range | 最小年龄区间 |
| age_max_years | integer · eq range | 最大年龄区间 |
| completion_year | integer · eq range | 完成年份区间 |
参数
| 参数 | 类型 | 说明 |
|---|---|---|
| query 必填 | string | 1–1000 字符。也可以是最多 5 条的数组（批量，hits 变 results[]）。 |
| top_k | integer= 10 | 1–100。 |
| fields | brief · head= brief | head 多扣 1 credit，每条附 head 视图。 |
| filters | json | 过滤 DSL 对象（见快速开始）；可用字段见上表。 |
| mode | hybrid · dense · bm25= hybrid | 检索模式。不传就用第一个。 |
| offset | integer= 0 | 翻页。 |
示例
{ "domain": "trials", "query": "…", "hits": [ { "id": "NCT02082496", "score": 0.83, "brief": { … } } ], "total": null, "coverage": …, "warnings": [],
"meta": { "request_id": "req_…", "credits": { "charged": 2, "balance": 1998, "pool": "allowance" }, "latency_ms": 41, "cached": false } } 用了未声明的过滤字段返回 400，不会静默忽略。过滤条件是 AND；可用
_or / _not。读
GET
/v1/trials/read/{nct_id}三档深浅，不传就是
detail。免费样例：NCT02082496。三档
| 深浅 | credits | 返回 |
|---|---|---|
| brief | 1 | 卡片：做取舍够用的字段（检索结果里那张） |
| detail （默认） | 2 | 全部结构化字段（规则字段 + 模型字段，模型字段在 _enrich.fields 里列名） |
| full | 5 | 全文（建设中：登记记录全文（含各节原文）在 NAS ctgov/bulk，未进检索库） |
参数
| 参数 | 类型 | 说明 |
|---|---|---|
| nct_id (path) 必填 | string | 文档 id（nct_id）。 |
| level | brief · detail · full= detail | 读多深。 |
| format | json · md · html= json | 响应形态。 |
示例
{ "domain": "trials", "id": "NCT02082496", "level": "detail", "view": "head", "data": { … } | "text": "…", "token_count": 1834, "meta": { … } } 旧写法
GET /v1/trials/doc/{id}?view=… 仍然可用。批量读
POST
/v1/trials/read最多 50 个 id，同一档。查不到的 id 返回
error: "not_found"，不扣费。参数
| 参数 | 类型 | 说明 |
|---|---|---|
| ids 必填 | string[] | 文档 id 列表。 |
| level | brief · detail · full= detail | 所有 id 共用的档。 |
示例
{ "domain": "trials", "level": "detail", "docs": [ { "id": "…", "data": { … } }, { "id": "…", "error": "not_found" } ], "meta": { … } } Facets
GET
/v1/trials/facets?field={field}某个过滤字段的合法值，agent 不用猜；预聚合字段带计数，声明的枚举没有。免费、不需要 key。
参数
| 参数 | 类型 | 说明 |
|---|---|---|
| field 必填 | phase · overall_status · study_type · intervention_type · sponsor_class · sex · countries · condition_mesh | 有 facets 的过滤字段。 |
| limit | integer= 50 | 最多返回多少个值。 |
示例
{ "domain": "trials", "field": "…", "values": [ { "value": "…", "count": 3120 } ], "meta": { … } } 问registered key+ /stream
POST
/v1/trials/ask本域的 agentic 问答：模型按自描述把问题翻成检索（筛选 + 关键词），读详情后作答，引用写成 [trials: <标题>]；/stream 为 NDJSON，answer_delta 是边生成边发的真实片段。
effort low / medium / high 对应 50 / 100 / 200 credits。加 /stream 走 NDJSON，第一个事件一定是 billing。首个 answer_delta 之前失败会退款。参数
| 参数 | 类型 | 说明 |
|---|---|---|
| query 必填 | string | 1–2000 字符。问得具体；要数字就直接问数字。 |
| effort | low · medium · high= low | 检索轮数，也决定价格：50 / 100 / 200 credits。套餐限制最高档。 |
| verbose | bool= false | 返回工具调用轨迹（流式时多 tool_call / tool_result / thinking 事件）。 |
| top_k | integer= 10 | 预取候选数。 |
| stream_answer | bool= true | 仅流式：false 时只发一个 answer 事件。 |
| max_rounds | integer | 0–8，覆盖 effort 预设。 |
| force_answer_after | number | 秒；强制切入作答阶段。 |
| max_answer_tokens | integer= 4096 | 触顶时置 answer_truncated。 |
| language | string | 回答语言，默认跟随 query。 |
示例
{ "answer": "… [NCT02082496] …", "sources": [ … ], "stats": { "rounds": 1, "elapsed_s": 6.2, "answer_truncated": false }, "coverage"?: { … }, "meta": { "credits": { "charged": 50, … } } } 引用是真的——
answer 里的每个 id 都存在于本垂域（格式 [NCT02082496]）。sources 是召回集，不是引用列表。answer_truncated 表示不完整。