> For the complete documentation index, see [llms.txt](https://developers.ethos.network/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers.ethos.network/api-documentation/api-v1-deprecated/users.md).

# Users

## Overview

The Users API allows you to retrieve user information and search for users in the Ethos network. It provides endpoints for getting detailed user statistics including reviews and vouches, as well as searching for users by name, username, or userkey.

## Endpoints

### Get User Statistics

```
GET /api/v1/users/:userkey/stats
```

**Description**: Retrieves comprehensive statistics about a user, including review and vouch information.

**Authentication Required**: No

#### Parameters

**Path Parameters**

| Name      | Type   | Required | Description                                                                                                                  |
| --------- | ------ | -------- | ---------------------------------------------------------------------------------------------------------------------------- |
| `userkey` | string | Yes      | The userkey for the user. Can be in the format of "profileId:123", "address:0x1234...", or "service:x.com:username:username" |

**Query Parameters**

| Name        | Type   | Required | Description                                             |
| ----------- | ------ | -------- | ------------------------------------------------------- |
| `startDate` | string | No       | Filter statistics to data after this date (ISO format)  |
| `endDate`   | string | No       | Filter statistics to data before this date (ISO format) |

#### Responses

**Success Response**

**Code**: 200 OK

```json
{
  "ok": true,
  "data": {
    "reviews": {
      "received": 10,
      "positiveReviewPercentage": 90,
      "percentile": 85.5,
      "positiveReviewCount": 9,
      "negativeReviewCount": 1,
      "neutralReviewCount": 0
    },
    "vouches": {
      "staked": {
        "received": 5.0,
        "deposited": 2.0,
        "mutual": 1.5
      },
      "balance": {
        "received": 5.0,
        "deposited": 2.0,
        "mutual": 1.5
      },
      "count": {
        "received": 3,
        "deposited": 2,
        "mutual": 1
      },
      "percentile": {
        "received": 85.5,
        "deposited": 75.2,
        "mutual": 65.3
      }
    }
  }
}
```

| Property                                | Type    | Description                                                  |
| --------------------------------------- | ------- | ------------------------------------------------------------ |
| `ok`                                    | boolean | Success status                                               |
| `data`                                  | object  | User statistics data                                         |
| `data.reviews`                          | object  | Review statistics                                            |
| `data.reviews.received`                 | number  | Total number of reviews received                             |
| `data.reviews.positiveReviewPercentage` | number  | Percentage of positive reviews (excluding neutral reviews)   |
| `data.reviews.percentile`               | number  | Percentile ranking for reviews compared to all users (0-100) |
| `data.reviews.positiveReviewCount`      | number  | Number of positive reviews                                   |
| `data.reviews.negativeReviewCount`      | number  | Number of negative reviews                                   |
| `data.reviews.neutralReviewCount`       | number  | Number of neutral reviews                                    |
| `data.vouches`                          | object  | Vouch statistics                                             |
| `data.vouches.staked`                   | object  | Statistics about the amount of ETH staked                    |
| `data.vouches.staked.received`          | number  | Total ETH received as vouches                                |
| `data.vouches.staked.deposited`         | number  | Total ETH deposited as vouches                               |
| `data.vouches.staked.mutual`            | number  | Total ETH in mutual vouches                                  |
| `data.vouches.balance`                  | object  | Statistics about the current balance of vouches              |
| `data.vouches.balance.received`         | number  | Current balance of received vouches                          |
| `data.vouches.balance.deposited`        | number  | Current balance of deposited vouches                         |
| `data.vouches.balance.mutual`           | number  | Current balance of mutual vouches                            |
| `data.vouches.count`                    | object  | Statistics about the number of vouches                       |
| `data.vouches.count.received`           | number  | Number of vouches received                                   |
| `data.vouches.count.deposited`          | number  | Number of vouches deposited                                  |
| `data.vouches.count.mutual`             | number  | Number of mutual vouches                                     |
| `data.vouches.percentile`               | object  | Percentile rankings compared to all users                    |
| `data.vouches.percentile.received`      | number  | Percentile for received vouches (0-100)                      |
| `data.vouches.percentile.deposited`     | number  | Percentile for deposited vouches (0-100)                     |
| `data.vouches.percentile.mutual`        | number  | Percentile for mutual vouches (0-100)                        |

#### Example

**Request**

```bash
http GET https://api.ethos.network/api/v1/users/profileId:123/stats
```

**Request with Date Filters**

```bash
http GET https://api.ethos.network/api/v1/users/profileId:123/stats \
  startDate=2023-01-01 \
  endDate=2023-12-31
```

#### Notes

* The percentile values indicate how the user's stats compare to other users. Higher percentiles indicate better performance.
* If a user has multiple userkeys (e.g., multiple addresses or social accounts), the statistics are aggregated across all of them.
* For reviews, the positive review percentage excludes neutral reviews from the calculation.
* For vouches, the "received" statistics represent vouches made to the user, "deposited" statistics represent vouches made by the user, and "mutual" statistics represent cases where both users have vouched for each other.