# Users

The Users API lets you list and search users from your ClearFeed account. This is supported for accounts using either Slack or Microsoft teams as their monitoring system

## User Object

Users are represented as JSON objects with the following properties:

<table data-full-width="true"><thead><tr><th width="160">Name</th><th width="100">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>id</code></td><td>string</td><td>The external user ID from Slack or Microsoft Teams.</td></tr><tr><td><code>name</code></td><td>string</td><td>The display name of the user.</td></tr><tr><td><code>email</code></td><td>string</td><td>The user's email address, when available.</td></tr><tr><td><code>avatar</code></td><td>string</td><td>Avatar URL for the user, when available.</td></tr><tr><td><code>deleted</code></td><td>boolean</td><td>Whether the user has been deactivated or deleted in the source system.</td></tr><tr><td><code>is_bot</code></td><td>boolean</td><td>Whether the user is a bot account.</td></tr></tbody></table>

## Get Users

<mark style="color:blue;">`GET`</mark> `https://api.clearfeed.app/v1/rest/users`

Lists users from the connected monitoring system. You can use this endpoint in three modes:

* List users with pagination
* Search users by name/email using `query`
* Fetch specific users by passing one or more `ids`

#### Query Parameters

| Name              | Type    | Description                                                                                                                                                             |
| ----------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ids`             | string  | Optional. Comma-separated list of external user IDs to fetch. Maximum 100 IDs. Cannot be combined with `query` or `next_cursor`.                                        |
| `query`           | string  | Optional. Search string used to match users in the connected monitoring system. Cannot be combined with `ids`.                                                          |
| `include_deleted` | boolean | Optional. When supported by the connected monitoring system, include deleted/deactivated users in list or search results. Defaults to `false` for list/search requests. |
| `limit`           | integer | Optional. Number of users to return per page. Minimum `1`, maximum `100`, default `50`.                                                                                 |
| `next_cursor`     | string  | Optional. Base64-encoded pagination cursor returned in `response_metadata.next_cursor`. Cannot be combined with `ids`.                                                  |

### Notes

* When `ids` is provided, the response includes only the requested matching users.
* `response_metadata.next_cursor` is `null` when there are no more results.
* If the account is not connected to Slack or Microsoft Teams, this endpoint returns `406 Not Acceptable`.

### Example: List Users

```bash
curl --request GET \
  --url 'https://api.clearfeed.app/v1/rest/users?limit=2' \
  --header 'Authorization: Bearer YOUR_API_TOKEN'
```

### Example Response

```json
{
  "users": [
    {
      "id": "U01ABC234DE",
      "name": "Ava Johnson",
      "email": "ava@acme.com",
      "avatar": "https://avatars.slack-edge.com/2026-03-10/avatar_72.png",
      "deleted": false,
      "is_bot": false
    },
    {
      "id": "U01XYZ567FG",
      "name": "Liam Chen",
      "email": "liam@acme.com",
      "avatar": "https://avatars.slack-edge.com/2026-03-10/avatar_72_2.png",
      "deleted": false,
      "is_bot": false
    }
  ],
  "response_metadata": {
    "next_cursor": "Mg==",
    "count": 2
  }
}
```

### Example: Search Users

```bash
curl --request GET \
  --url 'https://api.clearfeed.app/v1/rest/users?query=ava&limit=10' \
  --header 'Authorization: Bearer YOUR_API_TOKEN'
```

### Example: Fetch Users by IDs

```bash
curl --request GET \
  --url 'https://api.clearfeed.app/v1/rest/users?ids=U01ABC234DE,U01XYZ567FG' \
  --header 'Authorization: Bearer YOUR_API_TOKEN'
```

### Example Response for ID Lookup

```json
{
  "users": [
    {
      "id": "U01ABC234DE",
      "name": "Ava Johnson",
      "email": "ava@acme.com",
      "avatar": "https://avatars.slack-edge.com/2026-03-10/avatar_72.png",
      "deleted": false,
      "is_bot": false
    }
  ],
  "response_metadata": {
    "next_cursor": null,
    "count": 1
  }
}
```

### Error Responses

* **400 Bad Request:** Invalid query parameter combination, such as using `ids` together with `query` or `next_cursor`, or passing an invalid `next_cursor`.
* **403 Forbidden:** The API token is missing, invalid, or does not have permission to access the API.
* **406 Not Acceptable:** The account is not connected to Slack or Microsoft Teams.