Fetch Posts

This guide will show you how to fetch Post data in different ways.


Lens Post data has a rich structure that includes the following information:

  • Author's details

  • Post Metadata content

  • App used to create the Post

  • Post Actions such as Collect action or community defined actions

  • Logged-In Post Operations

To illustrate how to fetch posts, we will use the following fragments, which includes the most common fields of a Post:

fragment Post on Post {  id  author {    ...Account  }  timestamp  app {    address    metadata {      name      logo    }  }  metadata {    ...PostMetadata  }  root {    ...NestedPost  }  quoteOf {    ...NestedPost  }  commentOn {    ...NestedPost  }  stats {    ...PostStats  }}

In the end of this guide, we will expand on some of the Post fields that are not fully covered in the example above.

Get a Post

Use the post query to fetch a single Post by ID or by transaction hash.

Fetching a Post by transaction hash is extremely useful when building a user experience where a user creates a Post and needs it presented back to them.

query {  post(    request: {      post: "42"
      # OR
      # txHash: TxHash!    }  ) {    ... on Post {      ...Post    }
    ... on Repost {      ...Repost    }  }}

List Posts

Use the paginated posts query to fetch a list of Posts based on the provided filters.

query {  posts(    request: {      filter: {        # accounts addresses        authors: ["0x1234…"]        # optional, the app used to create the post        # apps: [EvmAddress!]
        # optional, the type of post        # postTypes: [PostType!]
        # optional, filter by metadata        metadata: {          mainContentFocus: [IMAGE]
          # optional, filter by tags          # tags: PostMetadataTagsFilter
          # optional, filter by content warning          # contentWarning: PostMetadataContentWarningFilter        }      }      # optional, defaults to the Global Feed address      # forFeeds: [EvmAddress]    }  ) {    items {      ... on Post {        ...Post      }
      ... on Repost {        ...Repost      }    }    pageInfo {      prev      next    }  }}

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

Search Posts

Use the paginated searchPosts query to search for Posts based on the provided query.

query {  searchPosts(request: {    query: "Lens"
    # optional, filters    filter {      # optional, the type of post      # postTypes: [PostType!]
      metadata: {        mainContentFocus: [IMAGE]
        # optional, filter by tags        # tags: PostMetadataTagsFilter
        # optional, filter by content warning        # contentWarning: PostMetadataContentWarningFilter      }    }
    # optional, defaults to the Global Feed address    # forFeeds: [EvmAddress]  }) {    items {      ... on Post {        ...Post      }
      ... on Repost {        ...Repost      }    }    pageInfo {      prev      next    }  }}

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

Post References

List all posts that reference a specific post (e.g., comments, quotes, reposts).

Use the paginated postReferences query to fetch a list of Posts that reference a specific Post.

query {  postReferences(    request: {      referencedPost: "42"      referenceTypes: [COMMENT_ON]
      # optional, control visibily of hidden posts      # visibilityFilter: PostVisibilityFilter! = VISIBLE    }  ) {    items {      ... on Post {        ...Post      }
      ... on Repost {        ...Repost      }    }    pageInfo {      prev      next    }  }}

The visibilityFilter allows you to control the visibility of post replies hidden by the author. For more information, see the Moderating Own Threads guide.

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

Post Fields

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

Post Metadata

The metadata field of any Post contains the Post Metadata object that was linked to the post at the time of creation.

See the Create a Post guide for more information on how this object is created.

In GraphQL this is represented as a union type:

PostMetadata
union PostMetadata =    ArticleMetadata  | AudioMetadata  | CheckingInMetadata  | EmbedMetadata  | EventMetadata  | ImageMetadata  | LinkMetadata  | LivestreamMetadata  | MintMetadata  | SpaceMetadata  | StoryMetadata  | TextOnlyMetadata  | ThreeDMetadata  | TransactionMetadata  | VideoMetadata

If you used the @lens-protocol/metadata package to create the Post Metadata object, you will find the content of this union very familiar.

The union type allows to discriminate between different types of Post Metadata objects and access their specific fields. This is especially useful when rendering the Post in a UI because enables you to componentize the rendering logic based on the type of Post Metadata.

Mentions

The mentions field of a Post contains a list of all the accounts mentioned in the Post content.

fragment Post on Post {  mentions {    ...AccountMention  }}

Use the replace field to get the replacement information for the mentioned account.

Post Stats

The stats field of a Post contains the aggregated statistics of the Post, such as the total number of bookmarks, comments, reposts, quotes, reactions.

Post
fragment Post on Post {  stats {    bookmarks # Int!    comments # Int!    reposts # Int!    quotes # Int!    collects # Int!    upvotes: reactions(request: { type: UPVOTE }) # Int!    downvotes: reactions(request: { type: DOWNVOTE }) # Int!  }}

Use the reactions field to get the number of reactions of a specific type like shown in the example above.

Post Actions

In essence a Post Action is smart contract that can be attached to a Lens Post to expand its functionality.

The actions field of a Post contains a list of possible actions that can be performed on a given Post.

fragment Post on Post {  actions {    ... on SimpleCollectActionSettings {      ...SimpleCollectActionSettings    }
    ... on UnknownActionSettings {      ...UnknownActionSettings    }  }}

Lens API helps to make a distinction between protocol-native actions and community-defined actions, by giving a clear name to the former and leaving the latter as an UnknownActionSettings type.

See the Post Actions guide for more information on how to use this field to execute actions on a Post.

Logged-In Post Operations

The Lens API schema allows fetching detailed Post data when requests are made by a logged-in user (i.e., with an Access Token in the request headers). When the Post fragment includes the operations field, it provides insights into the user's interactions with the post and available actions.

The operations field in the response specifies both the actions the user can perform (e.g., canComment, CanRepost) and the actions already taken (e.g., hasReacted, hasCommented).

fragment Post {  operations {    canComment    canQuote    canRepost    isNotInterested    hasBookmarked    hasReported    hasReacted(request: { type: UPVOTE })    hasCommented {      ...BooleanValue    }    hasQuoted {      ...BooleanValue    }    hasReposted {      ...BooleanValue    }  }}

Where:

  • canComment: A TriStateValue indicating whether the user can comment on the post.

  • canQuote: A TriStateValue indicating whether the user can quote the post.

  • canRepost: A TriStateValue indicating whether the user can repost the post.

  • hasBookmarked: Indicates whether the user has bookmarked the post.

  • hasReported: Indicates whether the user has reported the post.

  • hasReacted: Indicates whether the user has reacted to the post.

  • hasCommented: A BooleanValue indicating whether the user has commented on the post.

  • hasQuoted: A BooleanValue indicating whether the user has quoted the post.

  • hasReposted: A BooleanValue indicating whether the user has reposted the post.

  • isNotInterested: Indicates whether the user has marked the post as not interesting.

Fields returning a TriStateValue can have three possible values: YES, NO, UNKNOWN. UNKNOWN means the Post Rule is not recognized by the Lens API, so it's unclear if the user can perform the action.

TriStateValue
enum TriStateValue {  YES  NO  UNKNOWN}

Fields returning a BooleanValue are operations that settles on-chain but could be optimistically assumed to be done.

BooleanValue
fragment BooleanValue on BooleanValue {  optimistic # true if the operation is optimistically assumed to be done  onChain # true if the operation is settled on-chain}