_include & _revinclude (R4 only)
The _include and _revinclude parameters request that the search results include additional resources ("included resources") related to the resources directly matching the query ("primary results"). Using these parameters is more efficient than making a series of requests to retrieve these additional resources separately.
Forward inclusion with _include adds resources and resource versions referenced by the primary results, and reverse inclusion with _revinclude adds resources that reference the primary results.
For example:
  • MedicationRequest?_include=MedicationRequest:subject searches over MedicationRequest resources, and for each resource returned also returns the target of the subject reference which might be a Group or Patient as defined in the FHIR specification.
  • MedicationRequest?_include=MedicationRequest:subject:Patient is similar but only returns subject references to Patient resources.
  • MedicationRequest?_revinclude=Provenance:target searches over MedicationRequest resources, and for each resource returned also returns any Provenance resources where the target reference on Provenance refers to the matching resource.
Important: Included resources do not count toward the page size. They will not be counted in Bundle.total and they might cause the number of returned resources to be larger than a specified _count parameter.
Warning: 1up APIs have limited support for _revinclude searches. The primary query must match no more than 1000 results or the search returns an error. Resource references within revinclude query have exceeded inner query limit


A wild card, *, indicates that all references available as search parameters should be included. You can use the * wild card as the first and only argument in the_include, or in place of the search parameter name from the standard _include, where the optional third value limits the resource type to a single type as in the original behavior.
For example:
  • Observation?_include=* searches over Observation resources, and for each resource also returns all referenced resources.
Copy link