--- name: "calendar_find_times" area: "calendar" title: "Find free times" price: "free" method: "POST" url: "https://api.conecto.chat/v1/tools/calendar_find_times" mcp_server: "https://api.conecto.chat/mcp/calendar" auth: "Authorization: Bearer " docs_url: "https://conecto.chat/tools/calendar/calendar_find_times" --- # Find free times (`calendar_find_times`) Free start times for a meeting type between two dates, in the time zone you ask for. Free start times for a meeting type between two dates (up to 62 days), shown in the time zone you ask for. For a round-robin type, host shows only that host's free times. Book one with calendar_book. Price: Free up to 1,000,000 reads a month for the whole account, then $0.50 per 10,000 reads. A call that fails costs nothing. ## Use it when Before booking: to offer someone times, or to check a time is free. ## Say this to your agent > Which bike fitting slots are still free next week? ## Inputs | Name | Type | Required | Description | Allowed values | Default | |---|---|---|---|---|---| | `meeting_type` | string | yes | Its slug, or "/" for a person's own type. | | | | `person` | string | no | The meeting type is on this person's own calendar. Up to 254 characters. | | | | `host` | string | no | A round-robin type: only this host. Up to 254 characters. | | | | `from` | string (date) | no | | | | | `to` | string (date) | no | | | | | `timezone` | string | no | Show times in this IANA zone (default: the calendar's). Up to 80 characters. | | | ## Example Written for Halverson Cycle & Repair, a bike shop with a repair workshop in Portland, Oregon. MCP: call `calendar_find_times` on the MCP server `https://api.conecto.chat/mcp/calendar` with these arguments: ```json { "meeting_type": "bike-fitting", "from": "2026-10-19", "to": "2026-10-24", "timezone": "America/Los_Angeles" } ``` REST: ```bash curl https://api.conecto.chat/v1/tools/calendar_find_times \ -H "Authorization: Bearer $CONECTO_KEY" \ -H "Content-Type: application/json" \ -d '{"meeting_type": "bike-fitting", "from": "2026-10-19", "to": "2026-10-24", "timezone": "America/Los_Angeles"}' ``` ## Response ```json { "call_id": "5f0c8a2e-3b7d-4c1e-9a64-2d8e1f7b0c93", "tool": "calendar_find_times", "status": "succeeded", "replayed": false, "cost_usd": "$0.00", "balance_usd": "$19.75", "result": { "meeting_type": "bike-fitting", "timezone": "America/Los_Angeles", "length_minutes": 45, "days": [ { "date": "2026-10-24", "starts": [ "2026-10-24T10:00:00-07:00", "2026-10-24T10:45:00-07:00" ] } ], "count": 8 } } ``` `result`: Free start times grouped by day in the requested time zone, the meeting length, and how many there are. ## Errors | Code | Status | When | Fix | |---|---|---|---| | `not_set_up` | 404 | The business has no calendar yet. | Create it with calendar_setup, then call again. | | `not_found` | 404 | No meeting type has that slug. | Call calendar_list_meeting_types and use one of its slugs. | | `invalid_input` | 400 | from or to is not a date, the range is too long, or the time zone is unknown. | Send dates like 2026-10-19, at most 62 days apart, and a zone like America/Los_Angeles. | | `not_a_host` | 400 | host is not one of the meeting type's round-robin hosts. | Leave host out, or name one of the hosts calendar_list_meeting_types shows. | The refusals every tool can give (401 key, 402 balance, 429 limits) are on the errors page: https://conecto.chat/docs/errors.md ## Related - [calendar_setup](https://conecto.chat/tools/calendar/calendar_setup.md): Sets the business's calendar or a person's own: name, booking address, time zone, weekly hours, closed days, reminder emails and confirmation calls. $0.001 a call. - [calendar_get_setup](https://conecto.chat/tools/calendar/calendar_get_setup.md): The calendar's settings, booking page, iCal link, connected Google calendar, meeting types, and its people's own calendars. Free up to 1,000,000 reads a month. - [calendar_connect](https://conecto.chat/tools/calendar/calendar_connect.md): A link that opens a page naming the business, where the owner, or a person for their own page, connects Google Calendar in one click. Free up to 1,000,000 reads a month. - [calendar_save_meeting_type](https://conecto.chat/tools/calendar/calendar_save_meeting_type.md): Creates or changes a kind of meeting people can book, on the business's calendar or a person's, taken by one host, a round robin or everyone. $0.001 a call. - [calendar_list_meeting_types](https://conecto.chat/tools/calendar/calendar_list_meeting_types.md): Every meeting type people can book, the business's and each person's own, with its hosts and booking page. Free up to 1,000,000 reads a month. - [calendar_book](https://conecto.chat/tools/calendar/calendar_book.md): Books a free time for someone, who gets a confirmation email with an invite and a link to change it. $0.01 a call. - [calendar_list_bookings](https://conecto.chat/tools/calendar/calendar_list_bookings.md): Bookings between two times (from now on by default), soonest first, with each one's hosts, guests and confirmation call. Free up to 1,000,000 reads a month. - [calendar_move](https://conecto.chat/tools/calendar/calendar_move.md): Moves a booking to another free time and sends the attendee an updated invite. $0.01 a call. - [calendar_cancel](https://conecto.chat/tools/calendar/calendar_cancel.md): Cancels a booking and tells the attendee by email, unless notify is false. $0.01 a call. - [calendar_save_routing_form](https://conecto.chat/tools/calendar/calendar_save_routing_form.md): Creates or changes a routing form that asks visitors a few questions and sends each to the right meeting type, host, site or message. $0.001 a call. - [calendar_list_routing_forms](https://conecto.chat/tools/calendar/calendar_list_routing_forms.md): The routing forms with their addresses, questions, routes and how many people answered each. Free up to 1,000,000 reads a month. - [calendar_list_routing_responses](https://conecto.chat/tools/calendar/calendar_list_routing_responses.md): What people answered on the routing forms, newest first, where each was sent, and the booking it led to. Free up to 1,000,000 reads a month.