Search Subjects

Full-text and faceted search across all ImmPort subjects/participants. Returns a compact shape: {total, returned, subjects, facets}. 'subjects' is a flat list of subject records (no OpenSearch envelope/score/highlight noise). 'facets' is omitted unless you pass the facets parameter. Useful for cross-study cohort discovery (e.g. find all female subjects in influenza studies). No authentication required.

Key parameters:

• term: partial matching by default; use quotes for exact phrase

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

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

• research_focus: e.g. 'Vaccine Response', 'Allergy'

• condition_or_disease: disease/condition name (use lookup_controlled_vocabulary('lkDisease'))

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

• clinical_trial: 'Y' or 'N'

• 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'))

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

• min_age: minimum subject age (numeric)

• age_range: age range string filter

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

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

• has_assessment: 'Y' or 'N'

• has_lab_test: 'Y' or 'N'

• 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, not when you just need the matching subjects 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' (a doc count, not a list of hidden values — raise facet_limit if you need the actual long-tail categories). study_accession/subject_accession are never returned as facets since they'd just duplicate the 'subjects' list.

• facet_limit: max buckets returned per facet (default 15). Raise this (e.g. 50, 100) when the 'other' bucket is large and you need the long-tail breakdown, not just top values.

• sort_field: field to sort by. Valid values: subject_accession (string sort), study_accession (string sort), assay_method, biosample_type, clinical_trial, condition_or_disease, ethnicity, sex, has_assessment, has_lab_test, min_age, race, research_focus, species

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

• search_fields: limit text search to specific fields

• source_fields: list of fields to return (e.g. ['study_accession', 'subject_accession']). Common fields: study_accession, subject_accession, condition_or_disease, research_focus, species, sex, race, ethnicity, min_age, max_age, assay_method, biosample_type, clinical_trial. For the FULL field list — including nested objects like pubmed (journal, year, doi), reagent, experiment, cde — dot-path projection syntax (e.g. 'pubmed.journal'), 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 the 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 subject (default False). Results are always returned in relevance order regardless of this flag.

EFFICIENCY TIPS:

• Cross-study questions (e.g. 'which subjects had assay 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.