app.bsky.feed.searchPostsV2

Find posts matching a search query or filters, returning search hits for matching post records.

class atproto_client.models.app.bsky.feed.search_posts_v2.Params

Bases: ParamsModelBase

Parameters model for app.bsky.feed.searchPostsV2.

field all_time: bool | None = None

Search the full index instead of the recent-post window.

field authors: List[AtIdentifier] | None = None

field cursor: str | None = None

Optional pagination cursor.

field domains: List[str] | None = None

Include posts that link to any of these domains.

field embedded_at_uris: List[AtUri] | None = None

Include posts that embed any of these AT URIs.

field exclude_authors: List[AtIdentifier] | None = None

field exclude_domains: List[str] | None = None

Exclude posts that link to any of these domains.

field exclude_embedded_at_uris: List[AtUri] | None = None

field exclude_hashtags: List[str] | None = None

field exclude_languages: List[Language] | None = None

field exclude_mentions: List[AtIdentifier] | None = None

field exclude_replies: bool | None = None

Exclude replies from results. Mutually exclusive with repliesOnly.

field exclude_urls: List[Uri] | None = None

Exclude posts that link to any of these URLs.

field following: bool | None = None

Include only posts from accounts followed by the viewer.

field has_media: bool | None = None

Include only posts with media.

field has_video: bool | None = None

Include only posts with video.

field hashtags: List[str] | None = None

field languages: List[Language] | None = None

field limit: int | None = None

Maximum number of results to return.

Constraints:

• ge = 1

• le = 100

field mentions: List[AtIdentifier] | None = None

field query: str | None = None

Search query string. A query or at least one filter is required.

field query_language: Literal['ja', 'zh', 'ko', 'th', 'ar'] | str | None = None

field replies_only: bool | None = None

Include only replies. Mutually exclusive with excludeReplies.

field reply_parent_uri: AtUri | None = None

Include only direct replies to this parent post URI.

field since: str | None = None

field sort: Literal['recent', 'top'] | str | None = None

field thread_root_uri: AtUri | None = None

field until: str | None = None

field urls: List[Uri] | None = None

Include posts that link to any of these URLs.

class atproto_client.models.app.bsky.feed.search_posts_v2.ParamsDict

Bases: TypedDict

all_time: NotRequired[bool | None]

Search the full index instead of the recent-post window.

authors: NotRequired[List[AtIdentifier] | None]

Include posts by any of these authors. Handles are resolved to DIDs before searching.

cursor: NotRequired[str | None]

Optional pagination cursor.

domains: NotRequired[List[str] | None]

Include posts that link to any of these domains.

embedded_at_uris: NotRequired[List[AtUri] | None]

Include posts that embed any of these AT URIs.

exclude_authors: NotRequired[List[AtIdentifier] | None]

Exclude posts by any of these authors. Handles are resolved to DIDs before searching.

exclude_domains: NotRequired[List[str] | None]

Exclude posts that link to any of these domains.

exclude_embedded_at_uris: NotRequired[List[AtUri] | None]

Exclude posts that embed any of these AT URIs.

exclude_hashtags: NotRequired[List[Annotated[str, FieldInfo(annotation=NoneType, required=True, metadata=[MaxLen(max_length=640)])]] | None]

exclude_languages: NotRequired[List[Language] | None]

Exclude posts whose language matches any of these language codes.

exclude_mentions: NotRequired[List[AtIdentifier] | None]

Exclude posts that mention any of these accounts. Handles are resolved to DIDs before searching.

exclude_replies: NotRequired[bool | None]

Exclude replies from results. Mutually exclusive with repliesOnly.

exclude_urls: NotRequired[List[Uri] | None]

Exclude posts that link to any of these URLs.

following: NotRequired[bool | None]

Include only posts from accounts followed by the viewer.

has_media: NotRequired[bool | None]

Include only posts with media.

has_video: NotRequired[bool | None]

Include only posts with video.

hashtags: NotRequired[List[Annotated[str, FieldInfo(annotation=NoneType, required=True, metadata=[MaxLen(max_length=640)])]] | None]

languages: NotRequired[List[Language] | None]

Include posts whose language matches any of these language codes.

limit: NotRequired[int | None]

Maximum number of results to return.

mentions: NotRequired[List[AtIdentifier] | None]

Include posts that mention any of these accounts. Handles are resolved to DIDs before searching.

query: NotRequired[str | None]

Search query string. A query or at least one filter is required.

query_language: NotRequired[Literal['ja', 'zh', 'ko', 'th', 'ar'] | str | None]

Language analyzer hint for the query text. If unset, the server auto-detects when possible.

replies_only: NotRequired[bool | None]

Include only replies. Mutually exclusive with excludeReplies.

reply_parent_uri: NotRequired[AtUri | None]

Include only direct replies to this parent post URI.

since: NotRequired[str | None]

Include posts indexed at or after this timestamp. Can be a datetime, or just an ISO date (YYYY-MM-DD).

sort: NotRequired[Literal['recent', 'top'] | str | None]

Ranking order for results. ‘recent’ sorts by recency; ‘top’ uses search ranking.

thread_root_uri: NotRequired[AtUri | None]

Include only posts in the thread rooted at this post URI.

until: NotRequired[str | None]

Include posts indexed before this timestamp. Defaults to the current time. Can be a datetime, or just an ISO date (YYYY-MM-DD).

urls: NotRequired[List[Uri] | None]

Include posts that link to any of these URLs.

class atproto_client.models.app.bsky.feed.search_posts_v2.Response

Bases: ResponseModelBase

Output data model for app.bsky.feed.searchPostsV2.

field cursor: str | None = None

Cursor for the next page of results.

field detected_query_languages: List[Literal['ja', 'zh', 'ko', 'th', 'ar'] | str] | None = None

field hits_total: int | None = None

Estimated total number of matching hits. May be rounded or truncated.

field posts: List[models.AppBskyFeedDefs.PostView] [Required]

Hydrated views of matching posts.