> 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/profiles.md).

# Profiles

## Overview

The Profiles API allows you to access user profile information within the Ethos network. It provides endpoints for querying individual profiles, recent profiles, directory listings, and various leaderboards.

## Endpoints

### XP Leaderboard

```
GET /api/v1/profiles/xp-leaderboard
```

**Description**: Returns profiles ranked by XP points in descending order.

**Authentication Required**: No

#### Parameters

**Query Parameters**

| Name    | Type   | Required | Description                                                                                                      |
| ------- | ------ | -------- | ---------------------------------------------------------------------------------------------------------------- |
| `since` | string | No       | Only include XP earned since this date/time (ISO date format like '2023-01-01' or duration string like '1month') |
| `limit` | number | No       | Number of results to return (defaults to 50)                                                                     |

#### Responses

**Success Response**

**Code**: 200 OK

```json
{
  "ok": true,
  "data": [
    {
      "id": 19867,
      "profileId": 17,
      "displayName": "sketch",
      "username": "eskacie",
      "avatarUrl": "https://pbs.twimg.com/profile_images/1874244830190329858/IcrIFc6L.jpg",
      "description": "Design / Code / Create / Collect",
      "score": 1964,
      "status": "ACTIVE",
      "totalXp": 3521336,
      "userkeys": [
        "profileId:17",
        "address:0x5586d438BE5920143c0f9B179835778fa81a544a",
        "address:0x6f95934abc01eedA154C832dF4a4E210cAF877eb",
        "service:x.com:1461538142217912326"
      ]
    }
  ]
}
```

| Property             | Type    | Description                                |
| -------------------- | ------- | ------------------------------------------ |
| `ok`                 | boolean | Success status                             |
| `data`               | array   | Array of user objects                      |
| `data[].id`          | number  | Unique user ID                             |
| `data[].profileId`   | number  | Profile ID                                 |
| `data[].displayName` | string  | User's display name                        |
| `data[].username`    | string  | User's username                            |
| `data[].avatarUrl`   | string  | URL to the user's avatar                   |
| `data[].description` | string  | User's description                         |
| `data[].score`       | number  | User's credibility score                   |
| `data[].status`      | string  | User's status (ACTIVE or INACTIVE)         |
| `data[].userkeys`    | array   | Array of userkeys associated with the user |
| `data[].totalXp`     | number  | Total XP points accumulated                |

#### Example

**Request**

```bash
http GET https://api.ethos.network/api/v1/profiles/xp-leaderboard since:='2023-01-01' limit:=5
```

**Response**

```json
{
  "ok": true,
  "data": [
    {
      "id": 19867,
      "profileId": 17,
      "displayName": "sketch",
      "username": "eskacie",
      "avatarUrl": "https://pbs.twimg.com/profile_images/1874244830190329858/IcrIFc6L.jpg",
      "description": "Design / Code / Create / Collect",
      "score": 1964,
      "status": "ACTIVE",
      "totalXp": 3521336,
      "userkeys": [
        "profileId:17",
        "address:0x5586d438BE5920143c0f9B179835778fa81a544a",
        "address:0x6f95934abc01eedA154C832dF4a4E210cAF877eb",
        "service:x.com:1461538142217912326"
      ]
    }
  ]
}
```

#### Notes

* By default, results are sorted by total XP in descending order (highest first).
* Limited to the top 50 profiles by default.
* The `since` parameter can be specified either as an ISO date string (e.g., '2023-01-01') or as a duration string (e.g., '1month', '1week').
* When using the `since` parameter, the API returns only users who have earned XP during the specified period. If no users have earned XP in that period, an empty array is returned.
* Results are cached for 5 minutes for better performance.
* Certain profiles, such as the main Ethos Network profile and administrative profiles, are excluded from the leaderboard.