Fetch Accounts

This guide will help you with fetching Account data from the Lens API.

Lens Account data is comprised of:

To illustrate how to fetch accounts, we will use the following fragment, which includes some of the most common fields of an 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.

import { evmAddress } from "@lens-protocol/client";import { fetchAccount } from "@lens-protocol/client/actions";import { client } from "./client";
const result = await fetchAccount(client, {  address: evmAddress("0x1234…"),});
if (result.isErr()) {  return console.error(result.error);}
const account = result.value;

query {  accountsBulk(    request: {      usernames: [        {          localName: "wagmi"
          # Optional. Defaults to lens/* namespace.          # namespace: EvmAddress        }        {          localName: "ape"
          # Optional. Defaults to lens/* namespace.          # namespace: EvmAddress        }      ]
      # OR a list of Account addresses      # addresses: [EvmAddress!]
      # OR a list of Legacy Profile IDs      # legacyProfileIds: [LegacyProfileId!] e.g., ["0x05", "0x06"]    }  ) {    address    username {      value    }    metadata {      name      picture    }  }}

import { fetchAccounts } from "@lens-protocol/client/actions";
import { client } from "./client";
const result = await fetchAccounts(client, {   filter: {    searchBy: {      localNameQuery: "wagmi",    }  }});
if (result.isErr()) {  return console.error(result.error);}
// items: Array<Account>const { items, pageInfo } = result.value;

Continue with the Pagination guide for more information on how to handle paginated results.

In this section we will expand on some of the Account fields that are not covered in the examples above.

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.

fragment Account on Account {  # ...
  username {    ...Username  }
  socialX: username(request: { namespace: "0x1234…" }) {    ...Username  }}

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:

type AccountMetadata {  # A bag of attributes.  attributes: [MetadataAttribute!]!
  # The profile bio as markdown.  bio: String
  # The profile cover picture.  coverPicture: URI
  # A unique identifier.  id: String!
  # The profile display name.  name: String
  # The profile picture.  picture: URI}

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 Account on Account {  # ...
  score}

The Lens schema allows logged-in users to fetch details about available actions and actions already taken, via the operations field.

type Account = {  operations: LoggedInAccountOperations | null;};
type LoggedInAccountOperations = {  isFollowedByMe: boolean;  isFollowingMe: boolean;  canFollow: OperationValidationOutcome | null;  canUnfollow: OperationValidationOutcome | null;  isMutedByMe: boolean;  isBlockedByMe: boolean;  hasBlockedMe: boolean;  canBlock: OperationValidationOutcome | null;  canUnblock: OperationValidationOutcome | null;  hasReported: boolean;};

The LoggedInAccountOperations type specifies the actions the user can perform (e.g., canFollow, canBlock) and the actions already taken (e.g., isFollowedByMe, isBlockedByMe).

Where:

Fields returning an OperationValidationOutcome give information on the feasibility of the operation. More details in the Querying Data guide.

The isFollowedByMe, isFollowingMe, canFollow, and canUnfollow fields accept an optional argument specifying the Graph address to check the follow status.

fragment LoggedInAccountOperations on LoggedInAccountOperations {  isFollowedByMeOnMyGraph: isFollowedByMe(request: { graph: "0x1234…" })
  isFollowingMeOnMyGraph: isFollowingMe(request: { graph: "0x1234…" })
  canFollowOnMyGraph: canFollow(request: { graph: "0x1234…" }) {    ...OperationValidationOutcome  }
  canUnfollowOnMyGraph: canUnfollow(request: { graph: "0x1234…" }) {    ...OperationValidationOutcome  }}

If an argument is not provided, the query follows a fallback approach: