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:

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.

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

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.

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.

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

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

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

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

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

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

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.

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:

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.

enum TriStateValue {  YES  NO  UNKNOWN}

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

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