> Calendly developer docs. For page Markdown, append .md to any URL. > Index: https://developer.calendly.com/llms.txt > API catalog: https://developer.calendly.com/.well-known/api-catalog > OpenAPI: https://developer.calendly.com/openapi/calendly-api.yaml > OAuth authorization server: https://calendly.com/.well-known/oauth-authorization-server > MCP protected resource: https://mcp.calendly.com/.well-known/oauth-protected-resource > Scheduling MCP endpoint: https://mcp.calendly.com > Docs search MCP: https://developer.calendly.com/_mcp/server # List User Busy Times GET https://api.calendly.com/user_busy_times Returns an ascending list of user internal and external scheduled events within a specified date range. Date range can be no greater than 1 week (7 days). **NOTE:** * This endpoint does not support traditional keyset pagination. * External events will only be returned for calendars that have "Check for conflicts" configured. > `availability:read` Reference: https://developer.calendly.com/api-docs/calendly-api/availability/list-user-busy-times ## Authentication - `Authorization` header (bearer token, required) — OAuth 2.0 - `Authorization` header (bearer token, required) — Personal Access Token ## Request ### Query parameters - `user` (string, required) — The uri associated with the user - `start_time` (string, required) — Start time of the requested availability range. Date cannot be in the past. - `end_time` (string, required) — End time of the requested availability range. Date must be in the future of start_time. ## Response ### 200 OK - `collection` (list of UserBusyTime, required) — The set of internal and external scheduled calendar events matching the criteria ## Errors ### 400 Bad Request Error Request is not valid - `title` (enum, required) - Allowed values: `Internal Server Error` - `message` (enum, required) - Allowed values: `The server encountered an unexpected condition that prevented it from fulfilling the request.` - `details` (list of ErrorResponseDetailsItem, optional) ### 401 Unauthorized Error Cannot authenticate caller - `title` (enum, required) - Allowed values: `Internal Server Error` - `message` (enum, required) - Allowed values: `The server encountered an unexpected condition that prevented it from fulfilling the request.` - `details` (list of ErrorResponseDetailsItem, optional) ### 403 Forbidden Error Caller not authorized to perform this action or insufficient scope - `List-user-busy-timesRequestForbiddenError` ### 404 Not Found Error Requested resource not found - `title` (enum, required) - Allowed values: `Internal Server Error` - `message` (enum, required) - Allowed values: `The server encountered an unexpected condition that prevented it from fulfilling the request.` - `details` (list of ErrorResponseDetailsItem, optional) ### 424 Failed Dependency Error Unable to access external calendar - `title` (string, required) - `message` (string, required) - `details` (list of ErrorResponseDetailsItem, optional) ### 500 Internal Server Error An error has occurred on the server - `title` (enum, required) - Allowed values: `Internal Server Error` - `message` (enum, required) - Allowed values: `The server encountered an unexpected condition that prevented it from fulfilling the request.` - `details` (list of ErrorResponseDetailsItem, optional) ## Types ### UserBusyTime An internal or external scheduled event for a given user - `type` (enum, required) — Indicates whether the scheduled event is internal ('calendly' or 'reserved') or external - Allowed values: `calendly`, `reserved`, `external` - `start_time` (string, required) — The start time of the scheduled event in UTC time - `end_time` (string, required) — The end time of the scheduled event in UTC time - `buffered_start_time` (string, optional) — The start time of the calendly event, as calculated by any "before" buffer set by the user - `buffered_end_time` (string, optional) — The end time of the calendly event, as calculated by any "after" buffer set by the user - `event` (UserBusyTimeEvent, optional) ### ErrorResponseDetailsItem - `message` (string, required) - `parameter` (string, optional) - `code` (string, optional) ### UserNotInOrganizationError Permission Denied or caller not authorized to perform this action - `title` (enum, optional) - Allowed values: `Permission Denied` - `message` (enum, optional) - Allowed values: `This user is not in your organization` ### InsufficientScopeError Caller does not have required oauth scopes - `title` (enum, required) - Allowed values: `Insufficient scope` - `message` (enum, required) - Allowed values: `This operation requires the scopes listed in the 'required_scopes' array.` - `required_scopes` (list of string, required) ### UserBusyTimeEvent - `uri` (string, required) — The uri associated with the calendly scheduled event ## Examples **Response** ```json { "collection": [ { "type": "calendly", "start_time": "2020-01-02T20:00:00.000000Z", "end_time": "2020-01-02T20:30:00.000000Z", "buffered_start_time": "2020-01-02T19:30:00.000000Z", "buffered_end_time": "2020-01-02T21:00:00.000000Z", "event": { "uri": "https://api.calendly.com/scheduled_events/AAAAAAAAAAAAAAAA" } }, { "type": "calendly", "start_time": "2020-01-05T20:00:00.000000Z", "end_time": "2020-01-05T20:30:00.000000Z", "buffered_start_time": "2020-01-05T19:30:00.000000Z", "buffered_end_time": "2020-01-05T21:00:00.000000Z", "event": { "uri": "https://api.calendly.com/scheduled_events/BBBBBBBBBBBBBBBB" } }, { "type": "reserved", "start_time": "2020-01-07T17:00:00.000000Z", "end_time": "2020-01-07T17:30:00.000000Z" }, { "type": "reserved", "start_time": "2020-01-07T18:00:00.000000Z", "end_time": "2020-01-07T18:30:00.000000Z" }, { "type": "external", "start_time": "2020-01-07T20:00:00.000000Z", "end_time": "2020-01-07T20:30:00.000000Z" } ] } ``` **SDK Code** ```python User Busy Times import requests url = "https://api.calendly.com/user_busy_times" querystring = {"end_time":"2020-01-08T20:30:00.000000Z","start_time":"2020-01-02T20:00:00.000000Z","user":"https://api.calendly.com/users/AAAAAAAAAAAAAAAA"} headers = {"Authorization": "Bearer "} response = requests.get(url, headers=headers, params=querystring) print(response.json()) ``` ```javascript User Busy Times const url = 'https://api.calendly.com/user_busy_times?end_time=2020-01-08T20%3A30%3A00.000000Z&start_time=2020-01-02T20%3A00%3A00.000000Z&user=https%3A%2F%2Fapi.calendly.com%2Fusers%2FAAAAAAAAAAAAAAAA'; const options = {method: 'GET', headers: {Authorization: 'Bearer '}}; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go User Busy Times package main import ( "fmt" "net/http" "io" ) func main() { url := "https://api.calendly.com/user_busy_times?end_time=2020-01-08T20%3A30%3A00.000000Z&start_time=2020-01-02T20%3A00%3A00.000000Z&user=https%3A%2F%2Fapi.calendly.com%2Fusers%2FAAAAAAAAAAAAAAAA" req, _ := http.NewRequest("GET", url, nil) req.Header.Add("Authorization", "Bearer ") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby User Busy Times require 'uri' require 'net/http' url = URI("https://api.calendly.com/user_busy_times?end_time=2020-01-08T20%3A30%3A00.000000Z&start_time=2020-01-02T20%3A00%3A00.000000Z&user=https%3A%2F%2Fapi.calendly.com%2Fusers%2FAAAAAAAAAAAAAAAA") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Get.new(url) request["Authorization"] = 'Bearer ' response = http.request(request) puts response.read_body ``` ```java User Busy Times import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.get("https://api.calendly.com/user_busy_times?end_time=2020-01-08T20%3A30%3A00.000000Z&start_time=2020-01-02T20%3A00%3A00.000000Z&user=https%3A%2F%2Fapi.calendly.com%2Fusers%2FAAAAAAAAAAAAAAAA") .header("Authorization", "Bearer ") .asString(); ``` ```php User Busy Times request('GET', 'https://api.calendly.com/user_busy_times?end_time=2020-01-08T20%3A30%3A00.000000Z&start_time=2020-01-02T20%3A00%3A00.000000Z&user=https%3A%2F%2Fapi.calendly.com%2Fusers%2FAAAAAAAAAAAAAAAA', [ 'headers' => [ 'Authorization' => 'Bearer ', ], ]); echo $response->getBody(); ``` ```csharp User Busy Times using RestSharp; var client = new RestClient("https://api.calendly.com/user_busy_times?end_time=2020-01-08T20%3A30%3A00.000000Z&start_time=2020-01-02T20%3A00%3A00.000000Z&user=https%3A%2F%2Fapi.calendly.com%2Fusers%2FAAAAAAAAAAAAAAAA"); var request = new RestRequest(Method.GET); request.AddHeader("Authorization", "Bearer "); IRestResponse response = client.Execute(request); ``` ```swift User Busy Times import Foundation let headers = ["Authorization": "Bearer "] let request = NSMutableURLRequest(url: NSURL(string: "https://api.calendly.com/user_busy_times?end_time=2020-01-08T20%3A30%3A00.000000Z&start_time=2020-01-02T20%3A00%3A00.000000Z&user=https%3A%2F%2Fapi.calendly.com%2Fusers%2FAAAAAAAAAAAAAAAA")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "GET" request.allHTTPHeaderFields = headers let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ```