ClinicalTrials Study Search¶
Searches ClinicalTrials.gov (API v2) for studies matching a condition or disease, with rich filtering and sorting options. Returns either structured JSON results or raw CSV content along with metadata about the query.
Usage¶
Use this node to discover clinical studies by condition (e.g., lung cancer) and refine results with optional terms like location, intervention, sponsors, and status filters. It typically feeds downstream nodes that analyze or display study lists; select JSON for programmatic processing or CSV for spreadsheet-style handling.
Inputs¶
| Field | Required | Type | Description | Example |
|---|---|---|---|---|
| condition_or_disease | True | STRING | Primary search query for the condition or disease. | lung cancer |
| format | True | STRING | Response format. Use 'json' for structured results or 'csv' for raw CSV text. | json |
| fields | False | STRING | Comma-separated list of fields to include in the response. Leave empty to use API defaults. | NCTId, BriefTitle, Condition |
| sort | False | STRING | Sorting directive. '@relevance' by default; supports API-supported sort expressions. | @relevance |
| count_total | False | BOOLEAN | If true, requests the API to include total study count (when supported by the endpoint and format). | true |
| other_terms | False | STRING | Additional free-text terms to include in the query. | phase 3 randomized |
| location_terms | False | STRING | Location-based query terms such as country, state, city, or facility names. | United States; California |
| title_acronym | False | STRING | Match on study titles or acronyms. | KEYNOTE |
| intervention_treatment | False | STRING | Filter by intervention or treatment terms. | Pembrolizumab |
| outcome_measures | False | STRING | Filter by outcome measure terms. | overall survival |
| sponsor_collaborator | False | STRING | Filter by sponsor or collaborator names. | Merck Sharp & Dohme LLC |
| lead_sponsor_name | False | STRING | Filter by lead sponsor name. | National Cancer Institute (NCI) |
| study_ids | False | STRING | Comma-separated list of study identifiers to match (e.g., NCT IDs). | NCT04000165,NCT04512345 |
| patient_search_area | False | STRING | Patient-centric search specifier (API-supported patient search area text). | within 50 miles of 94103 |
| filter_overallStatus | False | STRING | Comma-separated overall status filters. | AVAILABLE,COMPLETED |
| filter_ids | False | STRING | Additional filter IDs supported by the API (comma-separated). | hasUsFacility,hasResults |
Outputs¶
| Field | Type | Description | Example |
|---|---|---|---|
| results | STRING | The study search results. For format=json, a JSON string of the 'studies' array; for format=csv, the raw CSV text. | [{ "protocolSection": { ... } }, ...] or "NCTId,BriefTitle,...\nNCT04000165,..." |
| metadata | STRING | Query metadata as a JSON string. Includes fields like total_studies, query, api_version (for JSON), or format and content_length (for CSV). | { "total_studies": 128, "query": "lung cancer", "api_version": "2.0" } |
Important Notes¶
- Response format: Only 'json' and 'csv' are supported. Choose 'json' for structured processing and 'csv' for raw text.
- Field selection: Providing 'fields' limits the payload to specified fields; leave blank to use API defaults.
- Sorting and counts: The 'sort' and 'count_total' options depend on API support and may influence performance.
- Filters composition: Multiple filters can be combined; ensure values follow ClinicalTrials.gov API conventions (e.g., comma-separated lists).
- Rate limits and stability: External API availability or rate limiting may affect responses.
Troubleshooting¶
- Network error: Check internet connectivity, firewall settings, or retry later if the ClinicalTrials.gov API is unavailable.
- Empty results: Broaden 'condition_or_disease', remove restrictive filters, or verify field/filter names align with API capabilities.
- Unexpected CSV content: Confirm 'format' is set to 'csv' and that downstream nodes expect raw text, not parsed JSON.
- JSON decode error: Ensure 'format' is 'json' and that the response isn't an HTML or error page; inspect 'metadata' for clues.
- Large responses/timeouts: Reduce scope by narrowing 'fields', using fewer filters, or try again with a longer timeout upstream if configurable.