search_posts
Read-only
Search Bluesky posts by keyword with filters for author, language, date range, mentions, domain, and URL. Returns paginated results sorted by recency or engagement.
Instructions
Search for posts on Bluesky using full-text queries with optional filters for author, language, date range, mentions, domain, and URL. Returns a paginated list of matching posts sorted by recency or engagement. Requires authentication (app password). Use search_actors to find users instead of posts. Subject to per-tool rate limiting.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| q | Yes | Full-text search query string (1–300 characters). Supports keywords and hashtags (e.g. "#bluesky launch"). | |
| limit | No | Maximum number of posts to return per page (1–100, default 25). | |
| cursor | No | Opaque pagination cursor from the previous response cursor field; omit for the first page. | |
| sort | No | Sort order for results: "latest" returns newest posts first (default), "top" returns most-engaged posts first. | latest |
| since | No | ISO 8601 datetime lower bound (inclusive) for post creation time (e.g. "2024-01-01T00:00:00Z"). Omit to search all time. | |
| until | No | ISO 8601 datetime upper bound (exclusive) for post creation time (e.g. "2024-12-31T23:59:59Z"). Omit for no upper bound. | |
| mentions | No | Filter to posts that mention this handle or DID (e.g. "alice.bsky.social" or "did:plc:..."). | |
| author | No | Filter to posts authored by this handle or DID (e.g. "alice.bsky.social" or "did:plc:..."). Requires a non-empty q term. | |
| lang | No | BCP-47 language tag to filter posts by language (e.g. "en", "en-US", "pt-BR"). | |
| domain | No | Filter to posts containing links from this domain (e.g. "bsky.app"). Do not include protocol or path. | |
| url | No | Filter to posts containing this exact URL (must be a fully-qualified URL, e.g. "https://example.com/article"). |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| success | Yes | Whether the search request completed successfully. | |
| posts | Yes | Array of posts matching the search query. | |
| cursor | No | Opaque pagination cursor to pass as cursor in the next call; absent when no further pages exist. | |
| hasMore | Yes | True when a subsequent page of results is available. | |
| searchQuery | Yes | The search query string that was executed. | |
| totalResults | No | Approximate total number of matching posts reported by the API, if available. |