# 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

### Query Profiles

```
POST /api/v1/profiles
```

**Description**: Retrieves profile information for the specified profile IDs or addresses.

**Authentication Required**: No

#### Parameters

**Request Body**

```json
{
  "ids": [1, 2, 3],
  "addresses": ["0x1234...5678", "0xabcd...ef12"],
  "archived": false,
  "useCache": true,
  "limit": 10,
  "offset": 0
}
```

| Property    | Type             | Required | Description                                         |
| ----------- | ---------------- | -------- | --------------------------------------------------- |
| `ids`       | array of numbers | No\*     | Array of numeric profile IDs to query (maximum 100) |
| `addresses` | array of strings | No\*     | Array of Ethereum addresses to query (maximum 100)  |
| `archived`  | boolean          | No       | Whether to include archived profiles                |
| `useCache`  | boolean          | No       | Whether to use cached results (defaults to true)    |
| `limit`     | number           | Yes      | Number of results to return (maximum 100)           |
| `offset`    | number           | Yes      | Offset for pagination                               |

\*At least one of `ids` or `addresses` must be provided.

#### Responses

**Success Response**

**Code**: 200 OK

```json
{
  "ok": true,
  "data": {
    "values": [
      {
        "id": 1,
        "archived": false,
        "createdAt": 1737052979,
        "updatedAt": 1743189764,
        "invitesAvailable": 25,
        "invitedBy": 1
      }
    ],
    "limit": 10,
    "offset": 0,
    "total": 1
  }
}
```

| Property                         | Type    | Description                                         |
| -------------------------------- | ------- | --------------------------------------------------- |
| `ok`                             | boolean | Success status                                      |
| `data`                           | object  | Response data container                             |
| `data.values`                    | array   | Array of profile objects                            |
| `data.values[].id`               | number  | Unique profile ID                                   |
| `data.values[].archived`         | boolean | Whether the profile is archived                     |
| `data.values[].createdAt`        | number  | Unix timestamp of when the profile was created      |
| `data.values[].updatedAt`        | number  | Unix timestamp of when the profile was last updated |
| `data.values[].invitesAvailable` | number  | Number of invites available to this profile         |
| `data.values[].invitedBy`        | number  | ID of the profile that invited this user            |
| `data.limit`                     | number  | Number of results returned                          |
| `data.offset`                    | number  | Current pagination offset                           |
| `data.total`                     | number  | Total number of results matching the query          |

**Error Responses**

**Code**: 400 Bad Request

```json
{
  "ok": false,
  "error": {
    "code": "BAD_REQUEST",
    "message": "Must specify either ids or addresses",
    "fields": ["ids", "addresses"]
  }
}
```

#### Example

**Request**

```bash
http POST https://api.ethos.network/api/v1/profiles \
  ids:='[1]' \
  limit=10 \
  offset=0
```

**Response**

```json
{
  "ok": true,
  "data": {
    "values": [
      {
        "id": 1,
        "archived": false,
        "createdAt": 1737052979,
        "updatedAt": 1743189764,
        "invitesAvailable": 25,
        "invitedBy": 1
      }
    ],
    "limit": 10,
    "offset": 0,
    "total": 1
  }
}
```

#### Notes

* The API enforces a maximum of 100 profiles that can be requested at once.
* Results are returned in descending order by creation date (newest first).
* For performance reasons, it's recommended to use the `useCache` parameter.
* Timestamps are returned in Unix epoch format (seconds since January 1, 1970).

***

### 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.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://developers.ethos.network/api-documentation/api-v1-deprecated/profiles.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.