Get Upcoming Appointments
List the user's future visits from Appointment, Encounter, and CarePlan records
Returns the user's upcoming visits, earliest first, from future Appointment and Encounter records and from visits planned as scheduled CarePlan activities, leaving out cancelled visits and finished encounters. Use it for questions about everything on the user's calendar, such as "What visits do I have coming up?" or "Who am I seeing next week?" For appointments booked with a health system's scheduling, use get_appointments.
Set days_ahead to the period the question covers, such as 7 for next week.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
days_ahead | integer | No | Days after today to include. Default 365 |
count | integer | No | Most entries returned. Default 100 |
person_id | string | No | Leave unset. The server identifies the user from the access token, so keep patient identifiers out of prompts |
patient_id | string | No | Leave unset. The server identifies the user from the access token, so keep patient identifiers out of prompts |
Example
{"days_ahead": 30}{
"result": "2 upcoming appointments.",
"error": null,
"appointments": [
{
"appointment_id": "example-appointment-1",
"source_type": "Appointment",
"start_datetime": "2026-11-24T09:30:00-06:00",
"end_datetime": "2026-11-24T10:00:00-06:00",
"status": "booked",
"location_name": "Example Family Medicine",
"practitioner_name": "Dr. Sam Example",
"description": "Office visit"
},
{
"appointment_id": "example-careplan-1#activity-0",
"source_type": "CarePlan",
"start_datetime": "2026-12-08T15:00:00+00:00",
"end_datetime": null,
"status": "scheduled",
"description": "Diabetic eye exam"
}
],
"total_count": 2
}Reading the result
Times in appointments are ISO 8601 with the source record's UTC offset, and end_datetime can be null. Practitioner and location fields appear when the record has them, and CarePlan entries don't have them. One visit can appear twice, with different source_type values, when its CarePlan activity has no end time.
total_count is the number of entries in this response, which can be fewer than all upcoming visits. result shows the visits as a table, in the IANA time zone from the request's x-user-timezone header, or in UTC without it. With no visits, it reads No upcoming appointments found.
When one of the three reads fails, the call still succeeds, and error names the read, such as Encounter query: <message>, joined with ; when more than one fails. appointments then holds only the entries from the reads that succeeded.
Updated 1 day ago

