Bluesky Search icon

Bluesky Search

Search Bluesky posts using the AT Protocol

Overview

This node performs a search for posts on the Bluesky social network using the AT Protocol. It allows users to query posts with flexible search terms (supporting Lucene syntax) and apply various filters such as author, domain, language, date range, mentions, and hashtags. The results can be sorted by latest or top posts and limited in number.

Common scenarios where this node is beneficial include:

  • Monitoring specific topics or hashtags on Bluesky.
  • Gathering posts from particular authors or domains.
  • Analyzing trends or sentiment by filtering posts by language or time period.
  • Creating summaries of recent activity matching certain criteria.

For example, a user could search for posts mentioning a product launch hashtag within the last week, sorted by popularity, to gather insights for marketing analysis.

Properties

Name Meaning
Query Search query string supporting Lucene syntax; defines the main search terms (required).
Limit Maximum number of results to return (1 to 100).
Sort Sort order of results: "Latest" (most recent posts) or "Top" (most popular posts).
Additional Filters Collection of optional filters:
- Author Filter posts by a specific author's handle (e.g., handle.bsky.social).
- Domain Filter posts linking to a specific domain (e.g., example.com).
- Language Filter posts by language code (e.g., en for English).
- Since Include posts after this ISO 8601 datetime (e.g., 2025-01-01T00:00:00Z).
- Until Include posts before this ISO 8601 datetime (e.g., 2025-12-31T23:59:59Z).
- Mentions Filter posts mentioning a specific account handle.
- Tags Comma-separated list of hashtags (without #) to filter posts by tags.
Return Format Output format choice: "Individual Posts" returns each post separately; "Summary" returns an aggregated summary of the search results.

Output

The node outputs JSON data structured depending on the selected "Return Format":

  • Individual Posts (items):
    Each output item represents a single post with fields:

    • uri: Unique resource identifier of the post.
    • cid: Content identifier.
    • author: Object containing:
      • did: Decentralized ID of the author.
      • handle: Author's handle.
      • displayName: Author's display name.
      • avatar: URL to the author's avatar image.
    • text: Text content of the post.
    • createdAt: Post creation timestamp.
    • indexedAt: Timestamp when the post was indexed.
    • replyCount, repostCount, likeCount, quoteCount: Engagement metrics.
    • webLink: Direct URL to view the post on Bluesky.
    • rawPost: The full raw post object as returned by the API.

  • Summary (summary):
    A single JSON object summarizing the search:

    • query: The original search query string.
    • hits_total: Total number of matching posts found.
    • returned: Number of posts returned in this batch.
    • cursor: Cursor token for pagination (if any).
    • posts: Array of simplified post objects with:
      • uri
      • author (handle)
      • text
      • indexedAt
      • createdAt

No binary data output is produced by this node.

Dependencies

  • Requires an API key credential for authenticating with the Bluesky AT Protocol server.
  • Connects to the Bluesky API endpoint (default https://bsky.social) but can be configured to use a custom host.
  • Uses HTTP requests to:
    • Create a session and obtain an access token.
    • Perform the search query with specified parameters.

Troubleshooting

  • Missing or empty search query: The node throws an error if the "Query" property is empty or only whitespace. Ensure a valid search term is provided.
  • Authentication failure: If the node cannot obtain an access token, it will throw an error indicating failure to authenticate. Verify that the API key credentials are correct and have necessary permissions.
  • API request errors: Network issues or invalid parameters may cause HTTP request failures. Check connectivity and parameter formats (e.g., date strings must be ISO 8601).
  • Invalid filter values: Providing malformed filters (e.g., incorrect date format, improperly formatted tags) may result in no results or errors. Validate inputs before running.
  • Rate limits: The Bluesky API may enforce rate limits; excessive queries might lead to temporary blocking or errors.

Links and References

Discussion