> ## Documentation Index
> Fetch the complete documentation index at: https://api-docs.scholarlysoftware.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Inclusion of Related Resources

> Including related resources are a great way to make the most efficient use of the Scholarly API

Scholarly’s API is an implementation of the [JSON:API specification](https://jsonapi.org/).

One of the optional parts of this specification is [Inclusion of Related Resources](https://jsonapi.org/format/#fetching-includes) via the `?include` query parameter. Scholarly implements this parameter on all GET endpoints.

Bringing in these related resources is a great way to make fewer requests against the Scholarly API while still accomplishing your goal. Rather than needing to issue 1 request to fetch a list of users, and then N requests for their attached profiles, API clients are able to pull all of that down in one request.

These extra records are written to the top-level `included` JSON key. Here’s an example response to the `GET /api/v1/users?include=profile` endpoint:

```json theme={null}
{
  "data": [
    /* Users data found here */
  ],
  "included": [
    /* Profile data found here */
  ]
}
```

## Limitations

To prevent runaway queries, Scholarly limits all `?include` parameters to a depth of `2`. Any request specifying more than that will receive a `400 Bad Request`. Note, a depth of `2` means the `?include` parameter will have at most 1 period (`.`).

Here are a few examples:

```
# 200 OK
GET /api/v1/users?include=profile
GET /api/v1/users?include=profile.current_primary_appointment

# 400 Bad Request
GET /api/v1/users?include=profile.current_primary_appointment.rank
```

There is no limit to the number of 1- and 2-level relationships you can request:

```
# 200 OK
GET /api/v1/users?include=profile,addresses,phone_numbers
```