Date Filtering
Date filtering allows you to limit search results to the period that matters for your workflow. Use date parameters to restrict results based on when care occurred or when resources were updated. Applying date filters helps reduce payload size, improve performance, and construct accurate longitudinal records.
Date Parameters
You can apply date parameters when using the $everything or performing standard resource-level searches. The following parameters control how temporal filtering is applied.
| Parameter | Filters | When to Use | Example |
|---|---|---|---|
date | Clinical event date | Narrow resource results by when care occurred | Observation?patient=12345&date=ge2024-01-01 |
start | Clinical event date | Limit $everything results to events on or after the specified date | Patient/12345/$everything?start=2023-01-01 |
end | Clinical event date | Limit $everything results to events on or before the specified date | Patient/12345/$everything?end=2023-12-31 |
_lastUpdated | Server modification timestamp | Filter search results by when the resource was updated in the FHIR server | Observation?patient=12345&_lastUpdated=gt2025-02-01T00:00:00Z |
_since | Incremental updates | Retrieve only new or changed resources using $everything or asynchronous job completion | Patient/12345/$everything?_since=2025-02-01T00:00:00Z |
Filtering by Clinical Date
The date, start, and end parameters filter based on dates associated with the clinical event, not when the resource was ingested or updated. Filtering reflects the timeline of care rather than processing order.
| Resource type | Date field used |
|---|---|
Observation | Observation.effective[x] |
Encounter | Encounter.period.start and Encounter.period.end |
Condition | Condition.onset[x] and Condition.abatement[x] |
Procedure | Procedure.performed[x] |
MedicationRequest | MedicationRequest.authoredOn |
DocumentReference | DocumentReference.date |
Resources without clinical date attributes, such as Patient or Organization, aren't affected by date, start, or end, although they may still appear in bundle results for reference.
Examples
Retrieve observations occurring on or after the specified date:
GET /fhir/R4/Observation?patient=12345&date=ge2024-01-01
Retrieve documents within a specific clinical range:
GET /fhir/R4/DocumentReference?patient=12345&date=ge2023-01-01&date=le2023-12-31
Limit $everything results to events beginning on a specified date:
GET /fhir/R4/Patient/12345/$everything?start=2023-01-01
Filtering by Modification Timestamp
The _lastUpdated and _since parameters filter based on when the resource was last modified in the FHIR server, rather than when the clinical event occurred.
Examples
Use meta.lastUpdated to indicate when the resource was last modified:
"meta": {
"lastUpdated": "2025-02-12T14:23:57Z"
}
Retrieve resources updated after a specified timestamp:
GET /fhir/R4/Observation?patient=12345&_lastUpdated=gt2025-02-01T00:00:00Z
Use _since with $everything to return only incremental updates:
GET /fhir/R4/Patient/12345/$everything?_since=2025-02-01T00:00:00Z
Comparing Filters
The following examples illustrate the difference between filtering by clinical event date and filtering by modification timestamp.
Examples
Retrieve resources added or updated after February 1, 2025, regardless of when the clinical event occurred:
GET /fhir/R4/Patient/12345/$everything?_since=2025-02-01T00:00:00Z
Retrieve encounters that occurred on or after February 1, 2025, regardless of when the resource was last modified:
GET /fhir/R4/Encounter?patient=12345&date=ge2025-02-01
Timestamp Format
All timestamps follow the ISO 8601 format and are expressed in Coordinated Universal Time (UTC). Every timestamp includes a UTC time zone indicator (Z) to ensure consistent interpretation.
Example
"lastUpdated": "2025-02-12T14:23:57Z"
Your system should convert timestamps to local time zones for storage or display.
Combining Filters
You can combine filters with additional parameters such as patient, code, category, or _count.
Example
GET /fhir/R4/Observation?patient=12345&date=ge2024-01-01&_lastUpdated=gt2025-02-01T00:00:00Z&_count=50
Best Practices
- Use
date,start, andendfor clinical timelines - Use
_sincefor incremental retrieval when calling $everything - Use
_lastUpdatedto filter standard searches by modification timestamp - Always include
patientfor clinical resource searches - Combine temporal filters with
codeorcategoryto reduce payload size - Use pagination to retrieve large result sets efficiently