---
name: 1stauthor-trials
description: The 1stAuthor trials domain.
---

# 1stAuthor Trials

All 603,730 studies on ClinicalTrials.gov (one per NCT). Phase / status / enrolment / countries / MeSH come from the ctgov record; eligibility highlights, biomarkers, prior therapy, ECOG and one-line summaries are model-extracted.

Base URL `https://api.1stauthor.com`. Every call takes `Authorization: Bearer $FA_API_KEY`; the free samples named below work without a key. Free sample id: `NCT02082496`, free sample query: `glp-1 obesity phase 3`.

## Three verbs, every domain

```
POST /v1/{domain}/search  {query, filters?, top_k?}      → hits[].id + a card each
GET  /v1/{domain}/read/{id}?level=brief|detail|full      → read as deep as you need
POST /v1/{domain}/ask     {query, effort: low|medium|high} → an answer with real citations
```

`read` also takes `extra=<side>` for another side of the same document and `format=json|md|html`.
At `level=full`, `section=<name>` reads one section and `characters=N` the first N characters.

## Start here

- **Find trials** — `POST /v1/trials/search {"query": "GLP-1 用于肥胖的三期试验", "filters": {"phase": "PHASE3", "overall_status": "RECRUITING"}}`
- **Read one trial** — `GET /v1/trials/read/NCT02082496`
- **List a field's values** — `GET /v1/trials/facets?field=phase`

## Search filters

| field | type | meaning |
|---|---|---|
| `phase` | keyword · eq any | Trial phase |
| `overall_status` | keyword · eq any | Recruitment status |
| `study_type` | keyword · eq any | Study type |
| `intervention_type` | keyword · eq any | Intervention type |
| `condition_mesh` | keyword · eq any | Condition MeSH term (controlled, more reliable than free-text conditions) |
| `countries` | keyword · eq any | Trial countries |
| `start_year` | integer · eq range | Start year, range |
| `has_results` | bool · eq | Results posted |
| `sponsor_class` | keyword · eq any | Sponsor class |

Rarely needed, but valid: `sex`, `sponsor`, `intervention_mesh`, `biomarker_names`, `performance_status`, `treatment_naive`, `enrollment`, `age_min_years`, `age_max_years`, `completion_year`.

Filters combine with AND; `_or` / `_not` are available. Ranges are `{"gte": n}` / `{"lte": n}`, full text is `{"text": "…"}`.

## Read

| level | credits | returns |
|---|---|---|
| `brief` | 1 | Card: the fields needed to triage, same as in search hits |
| `detail` (default) | 2 | Every structured field (rule-derived plus model-generated; model fields are listed in _enrich.fields) |
| `full` | 5 | Full text (not available yet: the full registry record lives on NAS (ctgov/bulk) and is not in the index) |

## Ask

`POST /v1/trials/ask {query, effort}` — Agentic Q&A over this domain: the model turns the question into filters plus keywords from the domain's own self-description, reads the hits and answers with [trials:<nct_id> <title>] citations; /stream is NDJSON with real token deltas. Costs 50 / 100 / 200 credits by effort. Append `/stream` for NDJSON; the first event is always `billing`.

`sources` is the retrieval set, not the citation list — filter it by the ids that appear in `answer`. `answer_truncated` means the answer is incomplete; say so.

## Also here

- GET /v1/entities?q=<机构名> → 实体；GET /v1/entities/<id>/docs?domain=trials → 该机构在本域的文档

## Facets

`GET /v1/trials/facets?field=<field>` lists the legal values for `phase`, `overall_status`, `study_type`, `intervention_type`, `sponsor_class`, `sex`, `countries`, `condition_mesh` — free, no key. Use it instead of guessing a spelling.

## Working rules

- **Search first, read second.** A search hit is a card; decide from the card which ids deserve a read.
- **Read in layers.** `detail` answers most questions; go to `full` only when the answer is not in it.
- **Filters are declared.** An undeclared filter field is a 400, never a silent no-op. `GET /v1/{domain}` lists what exists.
- **Cite what you read.** Use the citation format below, and say plainly when the corpus has nothing.
- **Failures are not charged.** A 404 costs nothing; an upstream error is refunded. Quote `meta.request_id` when reporting one.

Citation format: `[NCT02082496]`.

## What this corpus will and will not tell you

- Filter by condition_mesh (controlled terms); `conditions` is free text as entered by the registrant.
- Eligibility highlights, biomarkers, prior therapy and ECOG are model-extracted from the eligibility text — verify against the record before acting.
- 97k studies carry overall_status=UNKNOWN: the registrant stopped updating, which does not mean the trial ended.
- The index holds no full text: level=full is not available yet (the full registry record lives on NAS (ctgov/bulk) and is not in the index).

---

Generated from https://api.1stauthor.com/v1/trials on 2026-10-14. Full reference: https://1stauthor.com/docs/trials/