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

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

Use the accounts query to fetch a finite number of accounts by their addresses, usernames, or legacy Lens v2 IDs.

query {  accounts(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: ["0x1234…", "0x5678…"]
    # OR a list of Legacy Profile IDs    # legacyProfileIds: ["0x05", "0x06"]  }) {    address    username    metadata {      name      picture    }  }}

Search Accounts

Use the paginated searchAccounts query to search for accounts by their usernames or metadata.

query {  searchAccounts(request: {    query: "bob"  }) {    items {      address      username      metadata {        name        picture      }    }    pageInfo {      prev      next    }  }}

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.

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

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.

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}

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.

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.