---
name: "directory_list_users"
area: "directory"
title: "List people in the directory"
price: "free"
method: "POST"
url: "https://api.conecto.chat/v1/tools/directory_list_users"
mcp_server: "https://api.conecto.chat/mcp/directory"
auth: "Authorization: Bearer <conecto_sk_ key>"
docs_url: "https://conecto.chat/tools/directory/directory_list_users"
---

# List people in the directory (`directory_list_users`)

People in the directory with their name, email, title, department and whether they can sign in.

People in the company's directory, with their id, name, email, title, department and whether they can sign in. query searches names and emails.

Price: Free up to 1,000,000 reads a month for the whole account, then $0.50 per 10,000 reads. A call that fails costs nothing.

## Use it when

Before changing someone, or to see who still has an account.

- For one person by email, use [directory_get_user](https://conecto.chat/tools/directory/directory_get_user.md).

## Say this to your agent

> Who in the warehouse still has an account?

## Inputs

| Name | Type | Required | Description | Allowed values | Default |
|---|---|---|---|---|---|
| `query` | string | no | Up to 100 characters. |  |  |
| `limit` | integer | no | 1 to 200. |  | `50` |

## Example

Written for Hansen & Voss, a restaurant-equipment wholesaler in Hamburg with 60 staff.

MCP: call `directory_list_users` on the MCP server `https://api.conecto.chat/mcp/directory` with these arguments:

```json
{
  "query": "warehouse",
  "limit": 50
}
```

REST:

```bash
curl https://api.conecto.chat/v1/tools/directory_list_users \
  -H "Authorization: Bearer $CONECTO_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "warehouse", "limit": 50}'
```

## Response

```json
{
  "call_id": "5f0c8a2e-3b7d-4c1e-9a64-2d8e1f7b0c93",
  "tool": "directory_list_users",
  "status": "succeeded",
  "replayed": false,
  "cost_usd": "$0.00",
  "balance_usd": "$19.75",
  "result": {
    "people": [
      {
        "id": "00u3",
        "name": "Jonas Becker",
        "email": "jonas.becker@hansenvoss.example",
        "title": "Warehouse operative",
        "department": "Warehouse",
        "enabled": true,
        "status": "active"
      }
    ],
    "count": 1
  }
}
```

`result`: people: each with id, name, email, title, department and enabled; count.

## Errors

| Code | Status | When | Fix |
|---|---|---|---|
| `not_connected` | 409 | No directory is connected yet. | Connect Entra ID or Okta with directory_connect. |
| `directory_rejected` | 502 | The directory refused, usually because a permission is missing. | Ask its admin to grant what the message names. |
| `directory_unavailable` | 503 | The directory could not be reached. | Try again in a minute; nothing changed. |

The refusals every tool can give (401 key, 402 balance, 429 limits) are on the errors page: https://conecto.chat/docs/errors.md

## Related

- [directory_connect](https://conecto.chat/tools/directory/directory_connect.md): Connects the company's Microsoft Entra ID or Okta, checked by reading one person. $0.001 a call.
- [directory_get_user](https://conecto.chat/tools/directory/directory_get_user.md): One person in the directory by id or email. Free up to 1,000,000 reads a month.
- [directory_list_groups](https://conecto.chat/tools/directory/directory_list_groups.md): The directory's groups with their id, name and description. Free up to 1,000,000 reads a month.
- [directory_create_user](https://conecto.chat/tools/directory/directory_create_user.md): Opens a joiner's account with their title, department and groups; no password passes Conecto. $0.25 a call.
- [directory_update_user](https://conecto.chat/tools/directory/directory_update_user.md): Changes a person's title, department or manager in the directory. $0.01 a call.
- [directory_set_groups](https://conecto.chat/tools/directory/directory_set_groups.md): Adds a person to groups and takes them out of others. $0.01 a call.
- [directory_suspend_user](https://conecto.chat/tools/directory/directory_suspend_user.md): Blocks a leaver's sign-in and ends their sessions, after the owner approves by default. $0.25 a call.
- [directory_restore_user](https://conecto.chat/tools/directory/directory_restore_user.md): Lets a suspended person sign in again. $0.001 a call.
- [directory_sync_from_hr](https://conecto.chat/tools/directory/directory_sync_from_hr.md): Sets titles and departments in the directory as HR has them; dry_run shows the plan first. $0.01 a call.
- [directory_disconnect](https://conecto.chat/tools/directory/directory_disconnect.md): Forgets the directory's credentials; nothing in the directory changes. Free.