> ## Documentation Index
> Fetch the complete documentation index at: https://docs.oneshotagent.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Clinical Trials

> Find the registered clinical studies that match a condition, a treatment or other search words.

Search the clinical studies registered with the US National Library of Medicine, in any country, for a condition, a treatment or other search words, most recently updated first. Each study gives its registry number, title, status, phases, study type, conditions, interventions, lead sponsor, enrollment, start and primary completion dates, the date it was last updated, the countries of its sites and a link to the study. Give `condition`, `query` or both, and optionally narrow by `status` (recruiting, not\_yet\_recruiting, active\_not\_recruiting, completed, terminated, withdrawn or suspended). Use it to see what research is registered on a disease or a drug, who sponsors it and how far along it is. A study record is what the sponsor registered, not a finding about a treatment. Contact and investigator details are not returned. `total` is how many studies matched, including any beyond `limit`, and is 0 when none did.

## Authentication

Requires x402 payment in the `payment-signature` header.

## Request Body

<ParamField body="condition" type="string">
  A condition or disease, for example psoriasis. 2 to 120 characters.
</ParamField>

<ParamField body="query" type="string">
  A treatment or other search words, for example secukinumab. 2 to 200 characters.
</ParamField>

<ParamField body="status" type="string">
  Only studies with this status: recruiting, not\_yet\_recruiting, active\_not\_recruiting, completed, terminated, withdrawn or suspended. One of `recruiting`, `not_yet_recruiting`, `active_not_recruiting`, `completed`, `terminated`, `withdrawn`, `suspended`.
</ParamField>

<ParamField body="limit" type="integer">
  The most studies to return. Default 10. From 1 to 20. Defaults to `10`.
</ParamField>

<Snippet file="audit-context-params.mdx" />

## Response (200 OK)

Top-level envelope: `success` (boolean) and `data` (object). All fields below are nested under `data`.

<ResponseField name="data.request_id" type="string">
  Durable job ID for audit and lookup
</ResponseField>

<ResponseField name="data.status" type="string">
  Job status: `completed`
</ResponseField>

<ResponseField name="data.tool" type="string">
  Always `record_clinical_trials_find`
</ResponseField>

<ResponseField name="data.result" type="object">
  The answer, described under Result below
</ResponseField>

<ResponseField name="data.evidence" type="object">
  Where the answer came from and when
</ResponseField>

<ResponseField name="data.evidence.source" type="string">
  The public body the data comes from. Always `US National Library of Medicine`.
</ResponseField>

<ResponseField name="data.evidence.source_kind" type="string">
  `public` when the data comes from a public body, `commercial` otherwise
</ResponseField>

<ResponseField name="data.evidence.retrieved_at" type="string">
  When the lookup was made, as an ISO 8601 UTC time
</ResponseField>

<ResponseField name="data.evidence.as_of" type="string">
  When the source says the fact was last updated, or `null` when the source gives no date
</ResponseField>

## Result

Nested under `data.result`.

<ResponseField name="data.result.total" type="number">
  How many studies matched, including any beyond `limit`.
</ResponseField>

<ResponseField name="data.result.studies" type="object[]">
  The matching studies, most recently updated first.
</ResponseField>

<ResponseField name="data.result.studies[].id" type="string">
  The registry number, for example NCT06399432. `null` when the source gives no value.
</ResponseField>

<ResponseField name="data.result.studies[].title" type="string">
  The brief title the sponsor gave the study. `null` when the source gives no value.
</ResponseField>

<ResponseField name="data.result.studies[].status" type="string">
  Where the study stands, for example recruiting or active\_not\_recruiting. `null` when the source gives no value.
</ResponseField>

<ResponseField name="data.result.studies[].phases" type="string[]">
  The phases, in upper case as the source gives them, for example PHASE2. An empty list means the source gives no phase, which is usual for an observational study; NA means the source marks phases as not applicable to the study.
</ResponseField>

<ResponseField name="data.result.studies[].study_type" type="string">
  interventional, observational or expanded\_access. `null` when the source gives no value.
</ResponseField>

<ResponseField name="data.result.studies[].conditions" type="string[]">
  The conditions the study addresses.
</ResponseField>

<ResponseField name="data.result.studies[].interventions" type="string[]">
  The treatments or other interventions studied.
</ResponseField>

<ResponseField name="data.result.studies[].sponsor" type="string">
  The lead sponsor. `null` when the source gives no value.
</ResponseField>

<ResponseField name="data.result.studies[].enrollment" type="number">
  The number of participants, planned or actual. `null` when the source gives no value.
</ResponseField>

<ResponseField name="data.result.studies[].start_date" type="string">
  When the study started, YYYY-MM-DD or YYYY-MM when only the month is given. `null` when the source gives no value.
</ResponseField>

<ResponseField name="data.result.studies[].primary_completion_date" type="string">
  When the primary outcome data are complete, YYYY-MM-DD or YYYY-MM. `null` when the source gives no value.
</ResponseField>

<ResponseField name="data.result.studies[].last_updated" type="string">
  When the record was last updated, YYYY-MM-DD. `null` when the source gives no value.
</ResponseField>

<ResponseField name="data.result.studies[].countries" type="string[]">
  The countries with a study site, each once.
</ResponseField>

<ResponseField name="data.result.studies[].url" type="string">
  The study on clinicaltrials.gov. `null` when the source gives no value.
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST https://win.oneshotagent.com/v1/tools/find/record-clinical-trials \
    -H "Content-Type: application/json" \
    -H "payment-signature: <base64 x402 payment>" \
    -d '{
      "condition": "psoriasis",
      "query": "secukinumab",
      "status": "recruiting",
      "limit": 1
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch("https://win.oneshotagent.com/v1/tools/find/record-clinical-trials", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "payment-signature": paymentProof,
    },
    body: JSON.stringify({
      "condition": "psoriasis",
      "query": "secukinumab",
      "status": "recruiting",
      "limit": 1
    }),
  });
  ```

  ```typescript SDK theme={null}
  const result = await agent.tool('find/record-clinical-trials', {
    condition: 'psoriasis',
    query: 'secukinumab',
    status: 'recruiting',
    limit: 1
  });
  console.log(result.data.result);
  console.log(result.data.evidence);
  ```
</RequestExample>

<ResponseExample>
  ```json Response (200) theme={null}
  {
    "success": true,
    "data": {
      "request_id": "uuid",
      "receipt_id": "rcpt_...",
      "status": "completed",
      "tool": "record_clinical_trials_find",
      "result": {
        "total": 1,
        "studies": [
          {
            "id": "NCT00000000",
            "title": "Example study of a treatment for psoriasis",
            "status": "recruiting",
            "phases": [
              "PHASE3"
            ],
            "study_type": "interventional",
            "conditions": [
              "Psoriasis"
            ],
            "interventions": [
              "Secukinumab"
            ],
            "sponsor": "Example Sponsor",
            "enrollment": 120,
            "start_date": "2025-03",
            "primary_completion_date": "2027-01",
            "last_updated": "2026-09-04",
            "countries": [
              "United States",
              "Germany"
            ],
            "url": "https://clinicaltrials.gov/study/NCT00000000"
          }
        ]
      },
      "evidence": {
        "source": "US National Library of Medicine",
        "source_kind": "public",
        "retrieved_at": "2026-10-13T12:00:00.000Z",
        "as_of": null
      }
    }
  }
  ```
</ResponseExample>

<Info>Price: \$0.005 per lookup. See [Pricing](/pricing) for every tool.</Info>

## Notes

* Results return inline. The finished job stays available at `/v1/requests/{request_id}`


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.