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

{
  "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

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

Request with Date Filters

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.