Fetch Accounts
This guide will help you with fetching Account data from the Lens API.
Lens Account data is comprised of:
Account Identity
Account Metadata
ML Score
Operational flags
To illustrate how to fetch accounts, we will use the following fragment, which includes some of the most common fields of an Account:
Account
fragment Account on Account { address username { value } metadata { name picture }}
In the end of this guide, we will expand on some of the fields that are not fully covered in the example above.
Get an Account
- TypeScript
- GraphQL
- React
Use the fetchAccount action to fetch an Account by its address, username, txHash or legacy Lens v2 ID.
import { fetchAccount } from "@lens-protocol/client/actions";
const result = await fetchAccount({username: 'wagmi'});
if (result.isErr()) { return console.error(result.error);}
const account = result.value;
List Accounts
- GraphQL
- React
- TypeScript
Use the accounts query to fetch a finite number of accounts by their addresses, usernames, or legacy Lens v2 IDs.
Search Accounts
- GraphQL
- React
- TypeScript
Use the paginated searchAccounts query to search for accounts by their usernames or metadata.
See the Pagination guide for more information on how to handle paginated results.
Account Fields
In this section we will expand on some of the Account fields that are not covered in the examples above.
Account Identity
An Account can have one or more usernames across different namespaces, but only one username per namespace.
By default, the username field returns the username in the lens/ namespace, if available. It also accepts an optional argument to specify a different namespace.
Account Metadata
Although briefly mentioned in the examples, the metadata field is a rich object that can include a variety of information about the account.
It contains the Account Metadata object that was linked to the Account at the time of creation or update. This object can include the following fields:
See the Create an Account guide for more information on how this object is created.
Account Score
The Lens team has implemented a series of measures to uphold the integrity of the Lens ecosystem. The Account Score is a probability-based measure that evaluates an account's signal strength, helping to reduce the impact of spammy behavior on the user experience. This score is calculated using a set of ML algorithms that consider factors like follower graphs, content, and other variables. Higher scores suggest a positive and active presence within the ecosystem.
Fragment
fragment Account on Account { # ...
score}
Logged-In Account Operations
The Lens API schema allows fetching detailed account data when requests are made by a logged-in user (i.e., with an Access Token in the request headers). When the Account fragment includes the operations field, it provides insights into the user's interactions with the account and available actions.
- GraphQL
- React
- TypeScript
The operations field in the response specifies both the actions the user can perform (e.g., canFollow, canBlock) and the actions already taken (e.g., isFollowedByMe, hasBlockedMe).
Fragment
fragment Account on Account { address username metadata { name picture } operations { isFollowedByMe isFollowingMe canFollow canUnfollow isMutedByMe isBlockedByMe hasBlockedMe canBlock canUnblock hasReported }}
Where:
isFollowedByMe: Indicates whether the logged-in account follows the account.
isFollowingMe: Indicates whether the account follows the logged-in account.
canFollow: Indicates whether the logged-in account can follow the account. This is a tri-state value (YES, NO, UNKNOWN). UNKNOWN means the account’s Follow Rule is not recognized by the Lens API, so it's unclear if the user can follow the account.
canUnfollow: Indicates whether the logged-in account can unfollow the account.
isMutedByMe: Indicates whether the account is muted by the logged-in account.
isBlockedByMe: Indicates whether the account is blocked by the logged-in account.
hasBlockedMe: Indicates whether the account has blocked the logged-in account.
canBlock: Indicates whether the logged-in account can block the account.
canUnblock: Indicates whether the logged-in account can unblock the account.
hasReported: Indicates whether the logged-in account has reported the account.
The isFollowedByMe, isFollowingMe, canFollow, and canUnfollow fields accept an optional argument specifying the Graph address to check the follow status.
If an argument is not provided, the query follows a fallback approach:
It first checks for a Graph address specified within the query scope.
If no Graph address is found, it defaults to using the Global Graph.