Lens Profile APIs

APIs for Profile Scores and Ranking

All profiles in the Lens ecosystem are scored and ranked every hour. The scores and rankings are then made available through 5 different APIs that clients can call depending on their use case.

For details on each strategy ID, see Profile Scoring Strategies

Profile Score

Purpose: Retrieve a single profile score on the Lens ecosystem

The /profile/score endpoint retrieves a single profile score. Each profile score ranges between 0 and 1, with 0 being the lowest score and 1 being the highest score.

This endpoint requires a strategy parameter as described in the Scoring Strategies section. This strategy simplifies the developer experience abstracting away the EigenTrust Local-Trust and Pre-Trust strategies. Each strategy is pre-computed on a daily basis and applied to each Lens profile.

By using the date parameter, you can choose a particular day when the strategies were generated. This is helpful to get a snapshot in time of where each profile scores and ranks are, to help develop time series metrics dashboards for each profile to see how their scores trend over time.

You can try out this API at this OpenAPI interface — https://openapi.lens.k3l.io

Profile Scores

Purpose: Retrieve a list of global profile scores on the Lens ecosystem

The /profile/scores endpoint retrieves a list of numeric profile scores and ranks in relations with all other profiles, ordered by the highest score. Each profile score ranges between 0 and 1, with 0 being the lowest score and 1 being the highest score.

This endpoint also returns a rank position, starting with 1 as the top-ranked profile calculated for the day, and n being the lowest ranked, with n being the number of profiles included in the converged scoring calculations for the day.

This endpoint requires a strategy parameter as described in the Scoring Strategies section. This strategy simplifies the developer experience abstracting away the EigenTrust Local-Trust and Pre-Trust strategies. Each strategy is pre-computed on a daily basis and applied to each Lens profile.

The results returned are paginated to 50 profiles per response by default. This can be managed with a limit parameter with pagination alongside an offset parameter (first record at offset position 0). To help with pagination, you can use the Profile Count endpoint to retrieve the total number of profiles available.

By using the date parameter, you can choose a particular day when the strategies were generated. This is helpful to get a snapshot in time of where each profile scores and ranks are, to help develop time series metrics dashboards for each profile to see how their scores trend over time.

Profile Scores by Users

Purpose: Retrieve a list of global profile scores of a subset of users in the Lens ecosystem.

The /profile/scores_by_users endpoint retrieves a list of profile scores of a subset of users requested, and it will return with profile scores ranked in relations with all other profiles, ordered by the highest score. Each profile score ranges between 0 and 1, with 0 being the lowest score and 1 being the highest score.

This endpoint also returns a rank position, starting with 1 as the top-ranked profile calculated for the day, and n being the lowest ranked, with n being the number of profiles included in the converged scoring calculations for the day.

This endpoint requires a strategy parameter as described in the Scoring Strategies section. This strategy simplifies the developer experience abstracting away the EigenTrust Local-Trust and Pre-Trust strategies. Each strategy is pre-computed on a daily basis and applied to each Lens profile.

The results returned are paginated to 50 profiles per response by default. This can be managed with a limit parameter with pagination alongside an offset parameter (first record at offset position 0). To help with pagination, you can use the Profile Count endpoint to retrieve the total number of profiles available.

By using the date parameter, you can choose a particular day when the strategies were generated. This is helpful to get a snapshot in time of where each profile scores and ranks are, to help develop time series metrics dashboards for each profile to see how their scores trend over time.

Profile Count

Purpose: Retrieve the total number of profiles found on the Lens ecosystem

This /profile/count endpoint retrieves the total number of profiles scored for a particular strategy. The returned value is an unsigned integer.

This endpoint requires a strategy parameter as described in the Scoring Strategies section. This strategy simplifies the developer experience abstracting away the EigenTrust Local-Trust and Pre-Trust strategies. Each strategy is pre-computed on a daily basis and applied to each Lens profile.

There's a option to choose a particular day of how many profiles are available when the strategies were generated using the date parameter.

Profile Rank

Purpose: Retrieve a profile's score position, in relations to all other profiles, on the Lens ecosystem

This /profile/rank endpoint retrieves a particular profile's score position (ranked) for a particular strategy, in relations to all the other profiles in the Lens ecosystem. The returned value is an unsigned integer starting with 1.

This endpoint requires a strategy parameter as described in the Scoring Strategies section. This strategy simplifies the developer experience abstracting away the EigenTrust Local-Trust and Pre-Trust strategies. Each strategy is pre-computed on a daily basis and applied to each Lens profile.

There's a option to choose a particular day of how many profiles are available when the strategies were generated using the date parameter.

API Documentation

Tryout the APIs here! — https://openapi.lens.k3l.io

Return a paginated list of all profile scores

Returns the global profile scores, ordered by the highest scoring profiles, according to a given strategy.

GEThttps://lens-api.k3l.io/profile/scores

Query parameters

Response

200400500

Query succeeded.

Body

application/json

id*one of

Lens profile ID

integerstring

handle*string

Lens profile handle.

followersCount*integer

Number of followers.

scorenumber

Profile score of a user, ranges from 0 to 1

rankinteger

Ranking of a user (0 is the first place).

Request

JavaScriptCurlPython

const response = await fetch('https://lens-api.k3l.io/profile/scores', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

200400500

[
  {
    "id": 0,
    "handle": "text",
    "followersCount": 0,
    "score": 0,
    "rank": 0
  }
]

Display a user's profile score

Returns the global profile score of a user based on a strategy.

GEThttps://lens-api.k3l.io/profile/score

Query parameters

Response

200400500

Query succeeded.

Body

application/json

score*number (double)

The profile's score, between 0.0 and 1.0.

Request

JavaScriptCurlPython

const response = await fetch('https://lens-api.k3l.io/profile/score', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

200400500

{
  "score": 0
}

All scores for a given list of users

Returns the global profile scores of a list of users, ordered by the highest scoring profiles, according to a given strategy.

GEThttps://lens-api.k3l.io/profile/scores_by_users

Query parameters

Response

200400500

Query succeeded.

Body

application/json

id*one of

Lens profile ID

integerstring

handle*string

Lens profile handle.

followersCount*integer

Number of followers.

scorenumber

Profile score of a user, ranges from 0 to 1

rankinteger

Ranking of a user (0 is the first place).

Request

JavaScriptCurlPython

const response = await fetch('https://lens-api.k3l.io/profile/scores_by_users', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

200400500

[
  {
    "id": 0,
    "handle": "text",
    "followersCount": 0,
    "score": 0,
    "rank": 0
  }
]

Return the total population size of profiles scored

Returns the number of profiles available for a given strategy.

As an example, this can be used to display the number of pages on a paginated dashboard.

GEThttps://lens-api.k3l.io/profile/count

Query parameters

Response

200400500

Query succeeded.

Body

application/json

count*integer

The number of ranking entries (with non-zero trust).

Request

JavaScriptCurlPython

const response = await fetch('https://lens-api.k3l.io/profile/count', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

200400500

{
  "count": 0
}

Provide the ranked position of a given profile

Retrieves a particular profile's position ranked in relations to the result set of a strategy.

GEThttps://lens-api.k3l.io/profile/rank

Query parameters

Response

200400500

Query succeeded.

Body

application/json

rank*integer

The given profile's ranking (0 is the first place), based on the strategy specified.

Request

JavaScriptCurlPython

const response = await fetch('https://lens-api.k3l.io/profile/rank', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

200400500

{
  "rank": 0
}