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

# List Users — Shilo API Reference

> Retrieve a paginated list of users in your Shilo organization. Filter by external user ID, email, or name. Returns User objects with pagination cursor.

Use this endpoint to retrieve all users (agents) in your Shilo organization. Results are paginated and can be filtered by external user ID, email address, or name. Pass the `cursor` value from the pagination object into your next request to walk through large teams page by page.

## Endpoint

```
GET https://api.shilo.ai/api/v1/users
```

## Authentication

Include your API key in the request header:

```
x-api-key: YOUR_API_KEY
```

## Query Parameters

<ParamField query="limit" type="number" default="50">
  Maximum number of users to return per page. Accepted range is 1–100.
</ParamField>

<ParamField query="cursor" type="string">
  Pagination cursor returned by a previous response. Pass this value to retrieve the next page of results.
</ParamField>

<ParamField query="sort" type="string">
  Sort order by created date. Accepted values: `asc`, `desc`.
</ParamField>

<ParamField query="external_user_id" type="string">
  Filter by your system's user ID. Exact match only.
</ParamField>

<ParamField query="email" type="string">
  Filter by email address. Case-insensitive exact match.
</ParamField>

<ParamField query="name" type="string">
  Filter by user name. Case-insensitive partial match — useful for search-as-you-type UIs.
</ParamField>

## Response

A successful request returns HTTP `200` with a `UsersResponseDto` object.

### Response Fields

<ResponseField name="data" type="array">
  An array of User objects matching your query filters.

  <Expandable title="User object">
    <ResponseField name="id" type="string">
      The Shilo-assigned UUID for this user.
    </ResponseField>

    <ResponseField name="external_user_id" type="string">
      The user ID from your external system.
    </ResponseField>

    <ResponseField name="name" type="string">
      Full display name of the user.
    </ResponseField>

    <ResponseField name="email" type="string">
      Primary email address of the user.
    </ResponseField>

    <ResponseField name="timezone" type="string">
      The user's configured timezone in IANA format (e.g. `America/New_York`).
    </ResponseField>

    <ResponseField name="picture" type="string">
      URL of the user's profile picture, if set.
    </ResponseField>

    <ResponseField name="created_date" type="string">
      ISO-8601 timestamp indicating when this user was created in Shilo.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="pagination" type="object">
  Pagination metadata for the current response.

  <Expandable title="Pagination object">
    <ResponseField name="has_more" type="boolean">
      `true` if additional pages of results exist beyond the current page.
    </ResponseField>

    <ResponseField name="next_cursor" type="string | null">
      Cursor value to pass in your next request to retrieve the following page. `null` when no further pages are available.
    </ResponseField>
  </Expandable>
</ResponseField>

### Example Response

```json theme={null}
{
  "data": [
    {
      "id": "ee6f2136-b94a-4438-9335-3acf5b2a0d31",
      "external_user_id": "agent-1",
      "name": "Alex User",
      "email": "alex@example.com",
      "timezone": "America/New_York",
      "picture": "https://cdn.shilo.ai/avatars/ee6f2136.png",
      "created_date": "2024-01-15T09:00:00Z"
    }
  ],
  "pagination": {
    "has_more": false,
    "next_cursor": null
  }
}
```

## Error Codes

| Status | Meaning                     |
| ------ | --------------------------- |
| `401`  | Missing or invalid API key. |

## Example Request

```bash theme={null}
curl -X GET "https://api.shilo.ai/api/v1/users?limit=50&sort=asc" \
  -H "x-api-key: YOUR_API_KEY"
```

### Filter by name

```bash theme={null}
curl -X GET "https://api.shilo.ai/api/v1/users?name=alex" \
  -H "x-api-key: YOUR_API_KEY"
```

### Paginate with a cursor

```bash theme={null}
curl -X GET "https://api.shilo.ai/api/v1/users?limit=50&cursor=NEXT_CURSOR_VALUE" \
  -H "x-api-key: YOUR_API_KEY"
```