API Documentation
← All tools
GET/api/v1/tools/clinical/search-composite

Clinical Composite Search

clinicalAvailable on Free

Search clinical trials by disease, drug, target, and sponsor with combination filters. All parameters optional; at least one biological filter recommended. Returns paginated results, status breakdown, and full audit trail. disease/drug/target are resolved server-side (exact, alias, phrase, vector) and expanded to their graph ids; sponsor resolves via autocomplete + corporate hierarchy; status is an EXACT match on the stored UPPERCASE value (a mixed-case value returns no rows, not an error); phase accepts loose forms ('2', 'II', 'phase ii', 'Phase 2/3') normalized server-side, else a case-insensitive substring match. Failure modes: a disease/drug/target-ONLY query whose value cannot be resolved returns HTTP 500 naming the input (correct the name; repeating the same value cannot succeed); an unresolved entity inside a COMBINED query degrades to a 200 with totalCount 0; sponsor-only queries return 0 counts instead of an error. Target filters also return a data.mechanisms action-type summary; the status breakdown is empty for the single disease/drug/target fast paths.

When to use it

  • size a sponsor's portfolio in a disease
  • find trials combining sponsor + drug + disease filters

Getting started

Base URL

https://app.caelrith.com/api/v1/tools

Authentication

Include your API key in the x-api-key header.

Rate limit

Every call counts against your workspace’s daily quota for clinical-search-composite. Exceeding it returns HTTP 429.

Plans and daily limits

PlanAvailableCalls / day
freeyes10
proyes200
custom (default)yes10,000

Plan defaults. A custom workspace may carry per-tenant overrides.

Parameters

Query parameters

ParameterTypeRequiredDescription
sponsorstringNoSponsor name (resolves via autocomplete and hierarchy).
diseasestringNoDisease or condition name (resolved to ontology IDs such as EFO, MONDO).
drugstringNoDrug name (generic or brand, resolved to ChEMBL IDs).
targetstringNoBiological target (gene/protein) name or symbol.
phasestringNoClinical trial phase; loose forms are normalized server-side (e.g. 'Phase 2', '2', 'II', 'phase ii', 'Phase 2/3'), otherwise a case-insensitive substring fallback.
statusstringNoExact trial status in the stored UPPERCASE form (e.g. RECRUITING, COMPLETED, ACTIVE_NOT_RECRUITING). Case-sensitive - a mixed-case value returns no rows.
sponsorTypestringNo
includeSponsorsbooleanNobooleans arrive as strings - send 'true' or 'false'; value is parsed from the raw query string and coerced server-side
limitintegerNoResults per page (1-100, default 50). (range 1-100; default 50)
Range: 1 to 100
pageintegerNoPage number (default 1). (min 1; default 1)
Range: 1 to ∞

Example request

curl -H "x-api-key: YOUR_API_KEY" \
  "https://app.caelrith.com/api/v1/tools/clinical/search-composite"

Response envelope

Successful responses wrap the payload in a success flag.

{
  "success": true,
  "data": { /* payload */ },
  "meta": { /* pagination, totals */ }
}

Response shape

List responseTRIALS

Payload: data.trials — Clinical Trials

Exact total: data.totalCount

Breakdown: data.breakdown (fields: status → count)

Audit trail: data.audit_trail

Pagination: server-side via page and limit

Common row fields

FieldDescription
idID
titleTitle
statusStatus
phasePhase
startDateStart Date

Empty results: No matching rows (HTTP 200) (0 matched; an unresolvable disease/drug/target value inside a COMBINED query also yields 0 - verify the exact entity names before concluding no trials exist)

Catalog version mcp-2026-10-28 · generated from the live MCP catalog