# Return all calendars

> **GET** `https://api.us.nylas.com/v3/grants/{grant_id}/calendars`

Source: https://developer.nylas.com/docs/reference/api/calendar/get-all-calendars/

(Not supported for IMAP) Returns all calendars.

**Authentication:** NYLAS_API_KEY, ACCESS_TOKEN

## Parameters

### Query parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `select` | string | No | Specify fields that you want Nylas to return, as a comma-separated list (for example, `select=id,updated_at`). This allows you to receive only the portion of object data that you're interested in. You can use `select` to optimize response size and reduce latency by limiting queries to only the information that you need. |
| `limit` | integer | No | The maximum number of objects to return. See [Pagination](/docs/reference/api/#pagination) for more information. |
| `metadata_pair` | string | No | Pass a metadata key/value pair (for example, `?metadata_pair=key1:value`) to search for metadata associated with objects. See [Metadata](/docs/reference/api/#metadata) for more information. |
| `page_token` | string | No | An identifier that specifies which page of data to return. You can get this value from the `next_cursor` response field. See [Pagination](/docs/reference/api/#pagination) for more information. |

### Path parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `grant_id` | string | Yes | ID of the grant to access. You can also use the email address associated with the grant, or use `/me/` to refer to the grant associated with an access token. |

## Responses

### 200 - Calendars Response

- `request_id` (string) - The request ID.
- `data` (array)
  - `description` (string) - (Not supported for iCloud or EWS) A brief description of the calendar.
  - `grant_id` (string) - The ID of grant for the connected user.
  - `hex_color` (string) - (Not supported for iCloud or EWS) The background color of the calendar, in hexadecimal format (for
example, `#0099EE`). When empty, Nylas uses the default background color.

You can set or modify this value using a `PUT` request only.
  - `hex_foreground_color` (string) - (Google only) The foreground color of the calendar, in hexadecimal format (for example, `#0099EE`).
When empty, Nylas uses the default foreground color.

You can modify this value using a `PUT` request only.
  - `id` (string) - A globally unique object identifier for Microsoft accounts. An email address for Google accounts.
  - `is_owned_by_user` (boolean) - If `true`, indicates that the user owns the calendar. This field can't be modified once set.
  - `is_primary` (boolean) - If `true`, indicates that the calendar is the primary for the grant.
  - `location` (string) - (Not supported for iCloud or EWS) The geographic location of the calendar, as free-form text.
  - `metadata` (object) - The metadata associated with the object. For more information, see
[Metadata](/docs/reference/api/#metadata).
  - `name` (string) - The name of the calendar.
  - `object` (string) - The type of object.
  - `read_only` (boolean) - Set by the provider. If `true`, indicates that the calendar is read-only.

If the calendar is read-only, all of its events have `read_only` set to `true`. This field _cannot_
be modified.
  - `timezone` (string) - (Google and virtual calendars only) An [IANA timezone database](https://en.wikipedia.org/wiki/Tz_database)
formatted string (for example, `America/New_York`).
- `next_cursor` (string,null) - A cursor pointing to the next page of results for the request.

### 400 - Bad Request

- `request_id` (string) - The request ID.
- `error` (object) - The response error object.
  - `type` (string) - The error type.
  - `message` (string) - The error message.
  - `provider_error` (object) - The error from the provider.

### 401 - Unauthorized

- `request_id` (string) - The request ID.
- `error` (object) - The response error object.
  - `type` (string) - The error type.
  - `message` (string) - The error message.
  - `provider_error` (object) - The error from the provider.

### 429 - Rate Limit

- `request_id` (string) - The request ID.
- `error` (object) - The response error object.
  - `type` (string) - The error type.
  - `message` (string) - The error message.

### 504 - Provider Failure

- `request_id` (string) - The request ID.
- `error` (object) - The response error object.
  - `type` (string) - The error type.
  - `message` (string) - The error message.

## Code samples

### cURL

```bash
curl --request GET \
  --url 'https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/calendars' \
  --header 'Authorization: Bearer <NYLAS_API_KEY>' \
  --header 'Content-Type: application/json'
```

### Node.js SDK

```javascript
import Nylas from "nylas";

const nylas = new Nylas({
  apiKey: "<NYLAS_API_KEY>",
  apiUri: "<NYLAS_API_URI>",
});

async function fetchFiveAvailableCalendars() {
  try {
    const calendars = await nylas.calendars.list({
      identifier: "<NYLAS_GRANT_ID>",
      queryParams: {
        limit: 5,
      },
    });

    console.log("Available Calendars:", calendars);
  } catch (error) {
    console.error("Error fetching calendars:", error);
  }
}

fetchFiveAvailableCalendars();

```

### Python SDK

```python
from nylas import Client

nylas = Client(
    "<NYLAS_API_KEY>",
    "<NYLAS_API_URI>"
)

grant_id = "<NYLAS_GRANT_ID>"
calendars = nylas.calendars.list(grant_id)

print(calendars)
```

### Ruby SDK

```ruby
# Load gems
require 'nylas'

# Initialize Nylas client
nylas = Nylas::Client.new(
		api_key: "<NYLAS_API_KEY>"
)

# Build the query without parameters
listCalendersQueryParams = {}

# Build the query with parameters
returnFiveCalendars = {
	limit: 5
}

# Get a list of calendars
calendars, _request_ids = nylas.calendars.list(identifier: "<NYLAS_GRANT_ID>", 
		query_params: listCalendersQueryParams)

# Loop the calendars
calendars.each {|calendar|
	puts("Name: #{calendar[:name]} | " \
			"Description: #{calendar[:description]} | " \
			"Is Read Only?: #{calendar[:read_only]} | " \
			"Metadata: #{calendar[:metadata]}")
}

# Build the event parameters with metadata
CalendarsMetadata = {
	metadata_pair: {"key1":"This is my metadata"}
}

# Get a list of calendars
calendars, _request_ids = nylas.calendars.list(identifier: "<NYLAS_GRANT_ID>", 
		query_params: CalendarsMetadata)

puts ""                          
calendars.each {|calendar|
	puts calendar
}
```

### Kotlin SDK

```kotlin
// Import Nylas packages
import com.nylas.NylasClient
import com.nylas.models.*
import com.nylas.resources.Calendars

fun main(args: Array<String>) {

    // Initialize Nylas client
    val nylas: NylasClient = NylasClient(
        apiKey = "<NYLAS_API_KEY>"
    )

    // Build the query without parameters
    val calendarQueryParams: ListCalendersQueryParams = ListCalendersQueryParams()
    // Build the query with parameters
    val returnFiveCalendars: ListCalendersQueryParams = ListCalendersQueryParams(5)
    // Get all calendars
    val calendars: List<Calendar> = nylas.calendars().
                                    list("<NYLAS_GRANT_ID>",
                                    calendarQueryParams).data
                                    
    for(calendar in calendars){
        println("Id: " + calendar.id +
                " | Name: " + calendar.name +
                " | Description: " + calendar.description +
                " | Is Read Only?: " + calendar.readOnly +
                " | Metadata: " + calendar.metadata)
    }

    // Build the event parameters with metadata
    val calendarsMetadata: ListCalendersQueryParams = ListCalendersQueryParams(
                           metadataPair = mapOf("key1" to "This is my metadata"))
    val calendarsMeta: List<Calendar> = nylas.calendars().
    list("<NYLAS_GRANT_ID>",
        calendarsMetadata).data
    println()
    println(calendarsMeta)
}

```

### Java SDK

```java
// Import packages
import com.nylas.NylasClient;
import com.nylas.models.*;
import java.util.List;
import java.util.Map;

public class ReturnCalendars {
    public static void main(String[] args) throws NylasSdkTimeoutError, NylasApiError {
        // Initialize the Nylas client
        NylasClient nylas = new NylasClient.Builder("<NYLAS_API_KEY>").build();

        // Build the query without parameters
        ListCalendersQueryParams listCalendersQueryParams = 
                                 new ListCalendersQueryParams();
        // Build the query with parameters
        ListCalendersQueryParams returnFiveCalendars = new ListCalendersQueryParams.
                                                      Builder().limit(5).build();

        // Get all calendars
        List<Calendar> calendars = nylas.calendars().
                       list("<NYLAS_GRANT_ID>", listCalendersQueryParams).getData();

        // Loop the calendars
        for (Calendar calendar : calendars){
            // Print out the response
            System.out.println("Id: " + calendar.getId() +
                               " | Name: " + calendar.getName() +
                               " | Description: " + calendar.getDescription() +
                               " | Is Read Only?: " + calendar.getReadOnly() +
                               " | Metadata: " + calendar.getMetadata());
        }

        // Build the event parameters with metadata
        ListCalendersQueryParams CalendarsMetadata = new ListCalendersQueryParams.
                                                         Builder().
                                                         metadataPair(
                                                         Map.of("key1", 
                                                                "This is my metadata")
                                                         ).
                                                         build();
                                                         
        // Get all calendars that correspond to the metadata
        List<Calendar> metaCalendars = nylas.calendars().
                                       list("<NYLAS_GRANT_ID>", CalendarsMetadata).
                                       getData();
        // Print out the response
        System.out.println();
        System.out.println(metaCalendars);
    }
}

```