# Checking free/busy information

Source: https://developer.nylas.com/docs/v3/calendar/check-free-busy/

The Nylas APIs offer multiple ways to get information about users' availability, so you can book meetings or run other time-based operations. The simplest way to do so is using the [Free/Busy endpoint](/docs/v3/api-references/ecc/#post-/v3/grants/-grant_id-/calendars/free-busy), which returns simple information about blocks of time when they're booked on their `primary` calendar and _not_ available.

## How the Free/Busy endpoint works

When you make a request to the [Free/Busy endpoint](/docs/v3/api-references/ecc/#post-/v3/grants/-grant_id-/calendars/free-busy), Nylas returns a simple list of time slots during which the user's `primary` calendar is booked, and they're _not_ available.

When a user hasn't accepted an event on their calendar (for example, an event that's automatically added from an email invitation), providers handle it differently. Google marks that calendar as busy during that time span, while Microsoft marks it as free.

If you're querying a user within your organization, free/busy information is usually public. If you're querying a user outside of your organization, they must have published or made their calendar's free/busy information public.

![A calendar UI displaying the simple busy data returned by the Free/Busy endpoint.](/_images/calendar/busy-data.png "Busy data")

If the user is fully booked (there are no available time slots on their calendar), Nylas returns an empty `time_slots` array.

```json
[
  {
    "email": "jane.doe@example.com",
    "object": "free_busy",
    "time_slots": []
  }
]
```

Nylas recommends you use the Free/Busy endpoint when you need to know the times when a user's calendar is booked. If you need to do any of the following tasks, Nylas recommends you use the [Availability endpoint](/docs/v3/api-references/ecc/#post-/v3/calendars/availability) instead:

- Compare users' schedules.
- Check the status of room resources.

For more information, see [Check calendar availability](/docs/v3/calendar/calendar-availability/).

You can use the Free/Busy endpoint to check multiple users' calendars in the same call, but Nylas returns their individual busy data and does _not_ compare or combine it.

## Request busy data for a user

The following code snippet fetches a single user's busy data.

```bash

curl --compressed --request POST \
	--url 'https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/calendars/free-busy' \
	--header 'Accept: application/json' \
	--header 'Authorization: Bearer <NYLAS_API_KEY>' \
	--header 'Content-Type: application/json' \
	--data '{
		"start_time": 1682467200,
		"end_time": 1682550000,
		"emails": ["leyah@example.com"]
	}'

```

## Request busy data for multiple users

The following example fetches busy data for multiple users and shows the type of response you can expect from Nylas. You can use this request to view shared time slots for individuals using different providers, across multiple accounts and calendars.

> **Info:** 
> **Note**: You can include up to 20 email addresses for Microsoft Graph, and up to 50 email addresses for Google in a single request.

```bash
curl --request POST \
  --url 'https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/calendars/free-busy' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <NYLAS_API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
    "start_time": 1682467200,
    "end_time": 1682550000,
    "emails": [
      "leyah@example.com",
      "nyla@example.com"
    ]
  }'
```

```json [multiFreeBusy-Response (JSON)]
{
  "request_id": "dd3ec9a2-8f15-403d-b269-32b1f1beb9f5",
  "data": [
    {
      "email": "aristotle@example.com",
      "time_slots": [
        {
          "start_time": 1690898400,
          "end_time": 1690902000,
          "status": "busy",
          "object": "time_slot"
        },
        {
          "start_time": 1691064000,
          "end_time": 1691067600,
          "status": "busy",
          "object": "time_slot"
        }
      ],
      "object": "free_busy"
    },
    {
      "email": "nyla@example.com",
      "time_slots": [
        {
          "start_time": 1690898400,
          "end_time": 1690902000,
          "status": "busy",
          "object": "time_slot"
        },
        {
          "start_time": 1691064000,
          "end_time": 1691067600,
          "status": "busy",
          "object": "time_slot"
        }
      ],
      "object": "free_busy"
    },
    {
      "email": "jane@example.com",
      "error": "Unable to resolve e-mail address jane@example.com to an Active Directory object.",
      "object": "error"
    }
  ]
}
```