# Return a Folder

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

Source: https://developer.nylas.com/docs/reference/api/folders/get-folders-id/

Returns the specified folder.

**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. |
| `include_hidden_folders` | boolean | No | (Microsoft only) When `true`, Nylas includes hidden folders in its response. |
| `shared_from` | string | No | (Microsoft only) When provided, Nylas returns items that were shared from the specified email address. It also accepts grant ID. This parameter only accepts single email address or grant ID. Check out the [Shared folders](/docs/provider-guides/microsoft/shared-folders) guide for more information. |

### Path parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `grant_id` | string | Yes | ID of the grant to access. Use `/me/` to refer to the grant associated with an access token. |
| `folder_id` | string | Yes | ID of the folder to access. Nylas recommends you URL-encode this field, or you might receive a [`404` error](/docs/api/errors/400-response/) if the ID contains special characters (for example, `#`). |

## Responses

### 200 - Folder

- `request_id` (string) - The request ID.
- `data` (object) - An email folder or label.
  - `background_color` (string) - (Google only) The background color of the folder, in hexadecimal format (for example, `#0099EE`).
See the
[list of Google-defined values](https://developers.google.com/gmail/api/reference/rest/v1/users.labels#color)
for more information.
  - `child_count` (integer) - (Microsoft and EWS only) The number of immediate child folders nested under the specified folder.
  - `grant_id` (string) - The ID of grant for the connected user.
  - `id` (string) - A globally unique object identifier for Microsoft accounts. An email address for Google accounts.
  - `name` (string) - The name of the folder.
  - `object` (string) - The type of object.
  - `parent_id` (string) - (Microsoft and EWS only) The ID of the parent folder.
  - `single_level` (boolean) - (Microsoft only) If `true`, retrieves folders from a single-level hierarchy only. If `false`, retrieves folders across a multi-level hierarchy.
  - `system_folder` (boolean) - (Google only) If `true`, the folder is a standard folder created by Google. If `false`, the folder
was created by the user.
  - `text_color` (string) - (Google only) The text color of the folder, in hexadecimal format (for example, `#0099EE`). See
the
[list of Google-defined values](https://developers.google.com/gmail/api/reference/rest/v1/users.labels#color)
for more information.
  - `total_count` (integer) - The number of items inside the folder.
  - `unread_count` (integer) - The number of unread items inside the folder.
  - `attributes` (array) - An array of attribute descriptors shared by system folders across providers. For example, folders
that contain sent messages ("Sent Items" on Microsoft, or "SENT" on other providers) have the
`["\\Sent"]` attribute. For more information, see
[Common folder attributes](/docs/v3/email/folders/#common-folder-attributes). If a folder does not have one of the standard system folders, Nylas returns the `attributes` array empty.

You can't query for folders using attributes, but you _can_ manually filter through folders to
find any that match the attributes you're looking for.

### 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.

### 404 - Not Found

- `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 raw error from the provider, if available
    - `code` (string)
    - `message` (string)

### 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 --compressed --request GET \
  --url 'https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/folders/<FOLDER_ID>' \
  --header 'Accept: application/json' \
  --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 fetchFolderById() {
  try {
    const folder = await nylas.folders.find({
      identifier: "<NYLAS_GRANT_ID>",
      folderId: "<FOLDER_ID>",
    });

    console.log("Folder:", folder);
  } catch (error) {
    console.error("Error fetching folder:", error);
  }
}

fetchFolderById();

```

### Python SDK

```python
from nylas import Client

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

grant_id = "<NYLAS_GRANT_ID>"
folder_id = "<FOLDER_ID>"

message = nylas.folders.find(
  grant_id,
  folder_id,
)

print(message)
```

### Ruby SDK

```ruby
require 'nylas'

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

folder, _ = nylas.folders.find(identifier: "<NYLAS_GRANT_ID>", folder_id: "<FOLDER_ID>")

puts folder
```

### Java SDK

```java
import com.nylas.NylasClient;
import com.nylas.models.*;

public class GetLabel {

    public static void main(String[] args) throws 
    NylasSdkTimeoutError, NylasApiError {
        NylasClient nylas = new NylasClient.Builder("<NYLAS_API_KEY>").build();

        Response<Folder> folder = nylas.folders().find("<NYLAS_GRANT_ID>", 
        "<FOLDER_ID>");
        System.out.println(folder);
    }
}

```

### Kotlin SDK

```kotlin
import com.nylas.NylasClient

fun main(args: Array<String>) {

    val nylas: NylasClient = NylasClient(
        apiKey = "<NYLAS_API_KEY>"
    )

    val folder = nylas.folders().find("<NYLAS_GRANT_ID>", 
    "<FOLDER_ID>")
    print(folder)
}

```