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

ParameterTypeRequiredDescription
days_aheadintegerNoDays after today to include. Default 365
countintegerNoMost entries returned. Default 100
person_idstringNoLeave unset. The server identifies the user from the access token, so keep patient identifiers out of prompts
patient_idstringNoLeave 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.


Did this page help you?