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:
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
- GraphQL
- React
- TypeScript
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.
List Posts
- GraphQL
- React
- TypeScript
Use the paginated posts query to fetch a list of Posts based on the provided filters.
See the Pagination guide for more information on how to handle paginated results.
Search Posts
- GraphQL
- React
- TypeScript
Use the paginated searchPosts query to search for Posts based on the provided query.
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).
- GraphQL
- React
- TypeScript
Use the paginated postReferences query to fetch a list of Posts that reference a specific Post.
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.
- GraphQL
- React
- TypeScript
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.
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.
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).
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}