Search Studies

Full-text and faceted search across all ImmPort studies. Returns a compact shape: {total, returned, studies, facets}. 'studies' is a flat list of study records (no OpenSearch envelope/score/highlight noise). 'facets' is omitted unless you pass the facets parameter. Use this as the entry point for any study discovery workflow. No authentication required.

Key parameters:

• term: partial matching by default ('flu' finds 'influenza'); use quotes for exact phrase (e.g. '"influenza vaccine"')

• research_focus: e.g. 'Vaccine Response', 'Allergy', 'Autoimmune' (use lookup_research_focus() for valid values)

• condition_or_disease: disease/condition name, e.g. 'Influenza', 'Atopic Dermatitis' (use lookup_disease() for valid values)

• program_name: NIH program name, e.g. 'HIPC', 'ITN', 'SeroNet'

• clinical_trial: 'Y' or 'N' to filter to clinical trials only

• species: e.g. 'Homo sapiens', 'Mus musculus' (use lookup_controlled_vocabulary('lkSpecies'))

• sex: 'Female', 'Male', 'Unknown' (use lookup_controlled_vocabulary('lkSex'))

• race: e.g. 'White', 'Black or African American' (use lookup_controlled_vocabulary('lkRace'))

• ethnicity: e.g. 'Hispanic or Latino' (use lookup_controlled_vocabulary('lkEthnicity'))

• min_age: minimum subject age filter (numeric)

• age_range: age range string filter

• assay_method: measurement technique, e.g. 'Flow Cytometry', 'ELISA', 'RNA sequencing' (use lookup_controlled_vocabulary('lkExpMeasurementTech'))

• biosample_type: e.g. 'PBMC', 'Whole Blood', 'Serum' (use lookup_controlled_vocabulary('lkSampleType'))

• has_assessment: 'Y' or 'N'

• has_lab_test: 'Y' or 'N'

• study_accession: filter by specific study IDs, e.g. ['SDY1', 'SDY2']

• subject_accession: filter by specific subject IDs, e.g. ['SUB00240']

• facets: list of facet names to compute, e.g. ['assay_method', 'condition_or_disease']. Omit this (default) for discovery/lookup queries — no aggregations are computed, which keeps responses small and fast. Only request facets when the question is about distribution/breakdown (e.g. 'what assay types exist across these studies?'), not when you just need the matching studies themselves. Valid names: gender, race, ethnicity, species, clinical_trial, condition_or_disease, research_focus, assay_method, program_name, biosample_type, has_lab_test, has_assessment, age. Each returned facet is {value: count} for up to facet_limit non-zero values, with any remainder folded into 'other' (note: 'other' is a doc count, not a list of hidden values — if it's non-trivial and you need the actual long-tail categories, raise facet_limit rather than guessing). study_accession/subject_accession are never returned as facets since they'd just duplicate the 'studies' list.

• facet_limit: max buckets returned per facet (default 15). Raise this (e.g. 50, 100) when the 'other' bucket is large and you actually need the long-tail breakdown rather than just the top values — e.g. 'list every condition_or_disease in these results', not just the most common ones. Values ≤ 15 use the backend's cheapest pre-capped response; higher values cost more (the backend returns its full, still zero-count-trimmed, aggregation and the cap is applied here instead).

• sort_field: field to sort by. Valid values: study_accession_number (numeric — use desc for most recently added studies), study_accession (string sort only — do NOT use for recency), latest_data_release_date (date — use desc for most recently updated studies), latest_data_release_version_number (numeric release version, use desc for latest), initial_data_release_date (date — use desc for newest additions), initial_data_release_version_number (numeric), brief_title, min_age, max_age, condition_or_disease, research_focus, species, study_pi, actual_enrollment, planned_visit_total_count, shared_subject_count

• sort_field_direction: 'asc' (default) or 'desc'

• search_fields: limit text search to specific fields (comma-separated)

• source_fields: list of fields to return (e.g. ['study_accession', 'brief_title']). Common fields: study_accession, brief_title, brief_description, condition_or_disease, research_focus, species, study_pi, program_name, clinical_trial, assay_method, biosample_type, doi, pubmed_id. For the FULL field list — including nested objects like pubmed (journal, year, doi), reagent, experiment, personnel, cde — dot-path projection syntax (e.g. 'pubmed.journal'), fields that exist but can't be retrieved, and known data-quality caveats, see the immport://search-fields resource. '*' does NOT work as a wildcard for 'all fields' — it returns an empty object. Restrict to only fields you need to reduce response size.

• from_record: zero-based pagination offset (default 0)

• page_size: max records per page (default 10, hard cap 10000)

• include_score: adds a 'relevance_score' field to each study (default False). Results are always returned in relevance order regardless of this flag — only use this when you need the actual numeric score (e.g. to judge whether low-ranked hits are only tangentially related).

• include_highlights: adds a 'highlights' field to each study showing which text snippets matched term, e.g. distinguishing 'adjuvant vaccine' from 'adjuvant chemotherapy' (default False). Only meaningful when term is set; ignored otherwise. Not available on search_subjects (backend limitation).

EFFICIENCY TIPS:

• Cross-study questions (e.g. 'top journals', 'which studies used X'): use ONE call with page_size covering the full result set and narrow source_fields — do not loop get_study_data per study. See immport://query-tips for a worked example.

• source_fields: Always specify only the fields you need — omitting this returns full OpenSearch documents and produces very large responses.

• Sizing page_size: each row costs ~2,500 chars with full documents (no source_fields) vs. ~150 chars when source_fields is restricted to 2-3 fields. To fetch many results in one call instead of paginating, restrict source_fields first, then raise page_size (e.g. page_size=1000 with 2-3 source_fields is ~125KB; the same page_size with full documents would be ~2.5MB and likely exceed the response size limit). Don't raise page_size much past 50 unless source_fields is restricted.

• Pagination: Always check the top-level 'total' field. If total > page_size, issue additional calls incrementing from_record by page_size until all results are fetched.

• Parallel lookups: lookup_controlled_vocabulary is served from in-memory cache with no API cost — issue lookup calls in parallel with this search, not before it.

• Recency sort: use study_accession_number desc for most recently added; latest_data_release_date desc for most recently updated. Do NOT use study_accession for recency — it is a string (SDY10 sorts before SDY9).