Find posts matching search criteria, returning views of those posts. Note that this API endpoint may require authentication (eg, not public) for some service providers and implementations.
Parameters
author
string
at-identifier
Optional
Filter to posts by the given account. Handles are resolved to DID before query-time.
cursor
string
Optional
Optional pagination mechanism; may not necessarily allow scrolling through entire result set.
domain
string
Optional
Filter to posts with URLs (facet links or embeds) linking to the given domain (hostname). Server may apply hostname normalization.
lang
string
language
Optional
Filter to posts in the given language. Expected to be based on post language field, though server may override language detection.
limit
integer
Optional
No description provided.
mentions
string
at-identifier
Optional
Filter to posts which mention the given account. Handles are resolved to DID before query-time. Only matches rich-text facet mentions.
q
string
Required
Search query string; syntax, phrase, boolean, and faceting is unspecified, but Lucene query syntax is recommended.
since
string
Optional
Filter results for posts after the indicated datetime (inclusive). Expected to use 'sortAt' timestamp, which may not match 'createdAt'. Can be a datetime, or just an ISO date (YYYY-MM-DD).
sort
string
Optional
Specifies the ranking order of results.
tag
array
of string
Optional
Filter to posts with the given tag (hashtag), based on rich-text facet or tag field. Do not include the hash (#) prefix. Multiple tags can be specified, with 'AND' matching.
until
string
Optional
Filter results for posts before the indicated datetime (not inclusive). Expected to use 'sortAt' timestamp, which may not match 'createdAt'. Can be a datetime, or just an ISO date (YYY-MM-DD).
url
string
uri
Optional
Filter to posts with links (facet links or embeds) pointing to this URL. Server may apply URL normalization or fuzzy matching.
Output
application/jsoncursor
string
Optional
No description provided.
hitsTotal
integer
Optional
Count of search hits. Optional, may be rounded/truncated, and may not be possible to paginate through all hits.
posts
array
Required
No description provided.
Errors
BadQueryString
Try It
Requests are sent directly from your browser. Some servers may block requests due to CORS.
View raw schema
{
"type": "query",
"errors": [
{
"name": "BadQueryString"
}
],
"output": {
"schema": {
"type": "object",
"required": [
"posts"
],
"properties": {
"posts": {
"type": "array",
"items": {
"ref": "app.bsky.feed.defs#postView",
"type": "ref"
}
},
"cursor": {
"type": "string"
},
"hitsTotal": {
"type": "integer",
"description": "Count of search hits. Optional, may be rounded/truncated, and may not be possible to paginate through all hits."
}
}
},
"encoding": "application/json"
},
"parameters": {
"type": "params",
"required": [
"q"
],
"properties": {
"q": {
"type": "string",
"description": "Search query string; syntax, phrase, boolean, and faceting is unspecified, but Lucene query syntax is recommended."
},
"tag": {
"type": "array",
"items": {
"type": "string",
"maxLength": 640,
"maxGraphemes": 64
},
"description": "Filter to posts with the given tag (hashtag), based on rich-text facet or tag field. Do not include the hash (#) prefix. Multiple tags can be specified, with 'AND' matching."
},
"url": {
"type": "string",
"format": "uri",
"description": "Filter to posts with links (facet links or embeds) pointing to this URL. Server may apply URL normalization or fuzzy matching."
},
"lang": {
"type": "string",
"format": "language",
"description": "Filter to posts in the given language. Expected to be based on post language field, though server may override language detection."
},
"sort": {
"type": "string",
"default": "latest",
"description": "Specifies the ranking order of results.",
"knownValues": [
"top",
"latest"
]
},
"limit": {
"type": "integer",
"default": 25,
"maximum": 100,
"minimum": 1
},
"since": {
"type": "string",
"description": "Filter results for posts after the indicated datetime (inclusive). Expected to use 'sortAt' timestamp, which may not match 'createdAt'. Can be a datetime, or just an ISO date (YYYY-MM-DD)."
},
"until": {
"type": "string",
"description": "Filter results for posts before the indicated datetime (not inclusive). Expected to use 'sortAt' timestamp, which may not match 'createdAt'. Can be a datetime, or just an ISO date (YYY-MM-DD)."
},
"author": {
"type": "string",
"format": "at-identifier",
"description": "Filter to posts by the given account. Handles are resolved to DID before query-time."
},
"cursor": {
"type": "string",
"description": "Optional pagination mechanism; may not necessarily allow scrolling through entire result set."
},
"domain": {
"type": "string",
"description": "Filter to posts with URLs (facet links or embeds) linking to the given domain (hostname). Server may apply hostname normalization."
},
"mentions": {
"type": "string",
"format": "at-identifier",
"description": "Filter to posts which mention the given account. Handles are resolved to DID before query-time. Only matches rich-text facet mentions."
}
}
},
"description": "Find posts matching search criteria, returning views of those posts. Note that this API endpoint may require authentication (eg, not public) for some service providers and implementations."
}