Skip to content
FxEmbed

Search posts by query

GET
/2/search
 
curl --request GET \
  --url 'https://api.fxbsky.app/2/search?q=puppies&feed=latest&count=30&lang=es'

Search posts via Bluesky app.bsky.feed.searchPosts. Response shape matches FxTwitter GET /2/search (code, results, cursor). cursor.top is always null; pass cursor.bottom as the cursor query param. feed=latest and feed=top map to Bluesky sort. feed=media uses sort=latest then keeps posts with image, video, or external link embeds (may return fewer hits than count). lang is used for inline translation only, not the upstream post-language filter.

Parameters

Section titled “ Parameters ”

Query Parameters

Section titled “Query Parameters ”
q
required
string
Example 
puppies

Search query (non-empty)

feed
string
default: latest
Allowed values: latest top media

Search tab (default latest). media is a client-side filter on the current result page (no native Bluesky media tab).

count
integer
default: 30 >= 1 <= 100

Page size (default 30)

cursor
string

Pagination cursor from prior response (cursor.bottom)

lang
string
Example 
es

Target language (ISO 639-1 or BCP 47) for inline translation when available

Responses

Section titled “ Responses ”

200

Section titled “200 ”

Search results

Media type application/json
object
code
required
number
results
required
Array<object>
object
type
required

Discriminator: single status

string
Allowed values: status
id
required
string
cid
string
at_uri
string
url
required
string
text
required
string
created_at
required
string
created_timestamp
required
number
likes
required
number
reposts
required
number
quotes
number
replies
required
number
quote
Any of:
APIBlueskyStatus (recursive)

Recursive reference — same shape as APIBlueskyStatus.

object
poll
object
choices
required
Array<object>
object
label
required
string
count
required
number
percentage
required
number
total_votes
required
number
ends_at
required
string
time_left_en
required
string
author
required
object
type
required

Discriminator: full user profile (API v2).

string
Allowed values: profile
id
required
string
name
required
string
screen_name
required
string
avatar_url
required
string
nullable
banner_url
required
string
nullable
description
required
string
raw_description
required
object
text
required
string
facets
required
Array<object>
object
type
required

Facet kind: e.g. url, mention, hashtag, bold, media, custom_emoji (Mastodon custom emoji image)

string
indices
required

Start and end UTF-16 indices

Array<number>
>= 2 items <= 2 items
original
string
replacement
string
display
string
id
string
location
required
string
url
required
string
protected
required
boolean
followers
required
number
following
required
number
statuses
required
number
media_count
required
number
likes
required
number
joined
required
string
website
required
object
url
required
string
display_url
required
string
birthday
object
day
number
month
number
year
number
verification
object
verified
required
boolean
type
required
string
nullable
Allowed values: organization government individual
verified_at
string
nullable
identity_verified
boolean
verified_by
string
about_account
object
based_in
string
nullable
location_accurate
boolean
created_country_accurate
boolean
nullable
source
string
nullable
username_changes
object
count
required
number
last_changed_at
required
string
nullable
profile_embed
boolean
media
required
object
external
object
type
required
string
Allowed values: video
url
required
string
thumbnail_url
string
height
number
width
number
photos
Array<object>
object
id
string
format
string
type
required
string
Allowed values: photo gif
url
required
string
width
required
number
height
required
number
transcode_url
string
nullable
altText
string
videos
Array<object>
object
id
string
format
string
type
required
string
Allowed values: video gif
url
required
string
width
required
number
height
required
number
thumbnail_url
string
nullable
transcode_url
string
nullable
duration
required
number
filesize
number
formats
required
Array<object>
object
container
string
Allowed values: mp4 webm m3u8
codec
string
Allowed values: h264 hevc vp9 av1
bitrate
number
url
required
string
size
number
height
number
width
number
publisher
object
type
required

Discriminator: full user profile (API v2).

string
Allowed values: profile
id
required
string
name
required
string
screen_name
required
string
avatar_url
required
string
nullable
banner_url
required
string
nullable
description
required
string
raw_description
required
object
text
required
string
facets
required
Array<object>
object
type
required

Facet kind: e.g. url, mention, hashtag, bold, media, custom_emoji (Mastodon custom emoji image)

string
indices
required

Start and end UTF-16 indices

Array<number>
>= 2 items <= 2 items
original
string
replacement
string
display
string
id
string
location
required
string
url
required
string
protected
required
boolean
followers
required
number
following
required
number
statuses
required
number
media_count
required
number
likes
required
number
joined
required
string
website
required
object
url
required
string
display_url
required
string
birthday
object
day
number
month
number
year
number
verification
object
verified
required
boolean
type
required
string
nullable
Allowed values: organization government individual
verified_at
string
nullable
identity_verified
boolean
verified_by
string
about_account
object
based_in
string
nullable
location_accurate
boolean
created_country_accurate
boolean
nullable
source
string
nullable
username_changes
object
count
required
number
last_changed_at
required
string
nullable
profile_embed
boolean
all
Array
Any of:
object
id
string
format
string
type
required
string
Allowed values: photo gif
url
required
string
width
required
number
height
required
number
transcode_url
string
nullable
altText
string
mosaic
object
id
string
format
string
type
required
string
Allowed values: mosaic_photo
url
required
string
width
required
number
height
required
number
formats
required
object
webp
required
string
jpeg
required
string
broadcast
object
url
required
string
width
required
number
height
required
number
state
required
string
Allowed values: LIVE ENDED
broadcaster
required
object
username
required
string
display_name
required
string
id
required
string
stream
object
url
required
string
title
required
string
source
required
string
orientation
required
string
Allowed values: landscape portrait
broadcast_id
required
string
media_id
required
string
media_key
required
string
is_high_latency
required
boolean
thumbnail
required
object
original
required
object
url
required
string
small
object
url
required
string
medium
object
url
required
string
large
object
url
required
string
x_large
object
url
required
string
raw_text
required
object
text
required
string
facets
required
Array<object>
object
type
required

Facet kind: e.g. url, mention, hashtag, bold, media, custom_emoji (Mastodon custom emoji image)

string
indices
required

Start and end UTF-16 indices

Array<number>
>= 2 items <= 2 items
original
string
replacement
string
display
string
id
string
lang
required
string
nullable
translation
object
text
required
string
source_lang
required
string
source_lang_en
required
string
target_lang
required
string
provider
required
string
possibly_sensitive
required
boolean
replying_to
required
object
screen_name
required

Handle or account id used in permalinks (@user on X).

string
status
required

Parent post id (X: snowflake; Bluesky: record key).

string
url

Permalink to the parent post when known.

string
profile_url

Permalink to the parent author profile when known.

string
display_name

Display name of the parent author when known.

string
source
required
string
nullable
embed_card
required
string
Allowed values: tweet summary summary_large_image player
provider
required
string
Allowed values: bluesky
reposted_by
object
id
required
string
name
required
string
screen_name
required
string
avatar_url
string
nullable
url
string
cursor
required
object
top
required
string
nullable
bottom
required
string
nullable
Example 
{
  "results": [
    {
      "type": "status",
      "quote": {
        "type": "tombstone",
        "provider": "twitter",
        "reason": "deleted",
        "author": {
          "type": "profile",
          "verification": {
            "type": "organization"
          }
        }
      },
      "author": {
        "type": "profile",
        "verification": {
          "type": "organization"
        }
      },
      "media": {
        "external": {
          "type": "video"
        },
        "photos": [
          {
            "type": "photo"
          }
        ],
        "videos": [
          {
            "type": "video",
            "formats": [
              {
                "container": "mp4",
                "codec": "h264"
              }
            ],
            "publisher": {
              "type": "profile",
              "verification": {
                "type": "organization"
              }
            }
          }
        ],
        "all": [
          {
            "type": "photo"
          }
        ],
        "mosaic": {
          "type": "mosaic_photo"
        },
        "broadcast": {
          "state": "LIVE",
          "orientation": "landscape"
        }
      },
      "embed_card": "tweet",
      "provider": "bluesky"
    }
  ]
}

400

Section titled “400 ”

Invalid q parameter

Media type application/json
object
code
required
number
Allowed values: 400
message
required
string
Example 
{
  "code": 400
}

404

Section titled “404 ”

No results or search unavailable

Media type application/json
object
code
required
number
results
required
Array<object>
object
type
required

Discriminator: single status

string
Allowed values: status
id
required
string
cid
string
at_uri
string
url
required
string
text
required
string
created_at
required
string
created_timestamp
required
number
likes
required
number
reposts
required
number
quotes
number
replies
required
number
quote
Any of:
APIBlueskyStatus (recursive)

Recursive reference — same shape as APIBlueskyStatus.

object
poll
object
choices
required
Array<object>
object
label
required
string
count
required
number
percentage
required
number
total_votes
required
number
ends_at
required
string
time_left_en
required
string
author
required
object
type
required

Discriminator: full user profile (API v2).

string
Allowed values: profile
id
required
string
name
required
string
screen_name
required
string
avatar_url
required
string
nullable
banner_url
required
string
nullable
description
required
string
raw_description
required
object
text
required
string
facets
required
Array<object>
object
type
required

Facet kind: e.g. url, mention, hashtag, bold, media, custom_emoji (Mastodon custom emoji image)

string
indices
required

Start and end UTF-16 indices

Array<number>
>= 2 items <= 2 items
original
string
replacement
string
display
string
id
string
location
required
string
url
required
string
protected
required
boolean
followers
required
number
following
required
number
statuses
required
number
media_count
required
number
likes
required
number
joined
required
string
website
required
object
url
required
string
display_url
required
string
birthday
object
day
number
month
number
year
number
verification
object
verified
required
boolean
type
required
string
nullable
Allowed values: organization government individual
verified_at
string
nullable
identity_verified
boolean
verified_by
string
about_account
object
based_in
string
nullable
location_accurate
boolean
created_country_accurate
boolean
nullable
source
string
nullable
username_changes
object
count
required
number
last_changed_at
required
string
nullable
profile_embed
boolean
media
required
object
external
object
type
required
string
Allowed values: video
url
required
string
thumbnail_url
string
height
number
width
number
photos
Array<object>
object
id
string
format
string
type
required
string
Allowed values: photo gif
url
required
string
width
required
number
height
required
number
transcode_url
string
nullable
altText
string
videos
Array<object>
object
id
string
format
string
type
required
string
Allowed values: video gif
url
required
string
width
required
number
height
required
number
thumbnail_url
string
nullable
transcode_url
string
nullable
duration
required
number
filesize
number
formats
required
Array<object>
object
container
string
Allowed values: mp4 webm m3u8
codec
string
Allowed values: h264 hevc vp9 av1
bitrate
number
url
required
string
size
number
height
number
width
number
publisher
object
type
required

Discriminator: full user profile (API v2).

string
Allowed values: profile
id
required
string
name
required
string
screen_name
required
string
avatar_url
required
string
nullable
banner_url
required
string
nullable
description
required
string
raw_description
required
object
text
required
string
facets
required
Array<object>
object
type
required

Facet kind: e.g. url, mention, hashtag, bold, media, custom_emoji (Mastodon custom emoji image)

string
indices
required

Start and end UTF-16 indices

Array<number>
>= 2 items <= 2 items
original
string
replacement
string
display
string
id
string
location
required
string
url
required
string
protected
required
boolean
followers
required
number
following
required
number
statuses
required
number
media_count
required
number
likes
required
number
joined
required
string
website
required
object
url
required
string
display_url
required
string
birthday
object
day
number
month
number
year
number
verification
object
verified
required
boolean
type
required
string
nullable
Allowed values: organization government individual
verified_at
string
nullable
identity_verified
boolean
verified_by
string
about_account
object
based_in
string
nullable
location_accurate
boolean
created_country_accurate
boolean
nullable
source
string
nullable
username_changes
object
count
required
number
last_changed_at
required
string
nullable
profile_embed
boolean
all
Array
Any of:
object
id
string
format
string
type
required
string
Allowed values: photo gif
url
required
string
width
required
number
height
required
number
transcode_url
string
nullable
altText
string
mosaic
object
id
string
format
string
type
required
string
Allowed values: mosaic_photo
url
required
string
width
required
number
height
required
number
formats
required
object
webp
required
string
jpeg
required
string
broadcast
object
url
required
string
width
required
number
height
required
number
state
required
string
Allowed values: LIVE ENDED
broadcaster
required
object
username
required
string
display_name
required
string
id
required
string
stream
object
url
required
string
title
required
string
source
required
string
orientation
required
string
Allowed values: landscape portrait
broadcast_id
required
string
media_id
required
string
media_key
required
string
is_high_latency
required
boolean
thumbnail
required
object
original
required
object
url
required
string
small
object
url
required
string
medium
object
url
required
string
large
object
url
required
string
x_large
object
url
required
string
raw_text
required
object
text
required
string
facets
required
Array<object>
object
type
required

Facet kind: e.g. url, mention, hashtag, bold, media, custom_emoji (Mastodon custom emoji image)

string
indices
required

Start and end UTF-16 indices

Array<number>
>= 2 items <= 2 items
original
string
replacement
string
display
string
id
string
lang
required
string
nullable
translation
object
text
required
string
source_lang
required
string
source_lang_en
required
string
target_lang
required
string
provider
required
string
possibly_sensitive
required
boolean
replying_to
required
object
screen_name
required

Handle or account id used in permalinks (@user on X).

string
status
required

Parent post id (X: snowflake; Bluesky: record key).

string
url

Permalink to the parent post when known.

string
profile_url

Permalink to the parent author profile when known.

string
display_name

Display name of the parent author when known.

string
source
required
string
nullable
embed_card
required
string
Allowed values: tweet summary summary_large_image player
provider
required
string
Allowed values: bluesky
reposted_by
object
id
required
string
name
required
string
screen_name
required
string
avatar_url
string
nullable
url
string
cursor
required
object
top
required
string
nullable
bottom
required
string
nullable
Example 
{
  "results": [
    {
      "type": "status",
      "quote": {
        "type": "tombstone",
        "provider": "twitter",
        "reason": "deleted",
        "author": {
          "type": "profile",
          "verification": {
            "type": "organization"
          }
        }
      },
      "author": {
        "type": "profile",
        "verification": {
          "type": "organization"
        }
      },
      "media": {
        "external": {
          "type": "video"
        },
        "photos": [
          {
            "type": "photo"
          }
        ],
        "videos": [
          {
            "type": "video",
            "formats": [
              {
                "container": "mp4",
                "codec": "h264"
              }
            ],
            "publisher": {
              "type": "profile",
              "verification": {
                "type": "organization"
              }
            }
          }
        ],
        "all": [
          {
            "type": "photo"
          }
        ],
        "mosaic": {
          "type": "mosaic_photo"
        },
        "broadcast": {
          "state": "LIVE",
          "orientation": "landscape"
        }
      },
      "embed_card": "tweet",
      "provider": "bluesky"
    }
  ]
}

500

Section titled “500 ”

Upstream or processing error

Media type application/json
object
code
required
number
results
required
Array<object>
object
type
required

Discriminator: single status

string
Allowed values: status
id
required
string
cid
string
at_uri
string
url
required
string
text
required
string
created_at
required
string
created_timestamp
required
number
likes
required
number
reposts
required
number
quotes
number
replies
required
number
quote
Any of:
APIBlueskyStatus (recursive)

Recursive reference — same shape as APIBlueskyStatus.

object
poll
object
choices
required
Array<object>
object
label
required
string
count
required
number
percentage
required
number
total_votes
required
number
ends_at
required
string
time_left_en
required
string
author
required
object
type
required

Discriminator: full user profile (API v2).

string
Allowed values: profile
id
required
string
name
required
string
screen_name
required
string
avatar_url
required
string
nullable
banner_url
required
string
nullable
description
required
string
raw_description
required
object
text
required
string
facets
required
Array<object>
object
type
required

Facet kind: e.g. url, mention, hashtag, bold, media, custom_emoji (Mastodon custom emoji image)

string
indices
required

Start and end UTF-16 indices

Array<number>
>= 2 items <= 2 items
original
string
replacement
string
display
string
id
string
location
required
string
url
required
string
protected
required
boolean
followers
required
number
following
required
number
statuses
required
number
media_count
required
number
likes
required
number
joined
required
string
website
required
object
url
required
string
display_url
required
string
birthday
object
day
number
month
number
year
number
verification
object
verified
required
boolean
type
required
string
nullable
Allowed values: organization government individual
verified_at
string
nullable
identity_verified
boolean
verified_by
string
about_account
object
based_in
string
nullable
location_accurate
boolean
created_country_accurate
boolean
nullable
source
string
nullable
username_changes
object
count
required
number
last_changed_at
required
string
nullable
profile_embed
boolean
media
required
object
external
object
type
required
string
Allowed values: video
url
required
string
thumbnail_url
string
height
number
width
number
photos
Array<object>
object
id
string
format
string
type
required
string
Allowed values: photo gif
url
required
string
width
required
number
height
required
number
transcode_url
string
nullable
altText
string
videos
Array<object>
object
id
string
format
string
type
required
string
Allowed values: video gif
url
required
string
width
required
number
height
required
number
thumbnail_url
string
nullable
transcode_url
string
nullable
duration
required
number
filesize
number
formats
required
Array<object>
object
container
string
Allowed values: mp4 webm m3u8
codec
string
Allowed values: h264 hevc vp9 av1
bitrate
number
url
required
string
size
number
height
number
width
number
publisher
object
type
required

Discriminator: full user profile (API v2).

string
Allowed values: profile
id
required
string
name
required
string
screen_name
required
string
avatar_url
required
string
nullable
banner_url
required
string
nullable
description
required
string
raw_description
required
object
text
required
string
facets
required
Array<object>
object
type
required

Facet kind: e.g. url, mention, hashtag, bold, media, custom_emoji (Mastodon custom emoji image)

string
indices
required

Start and end UTF-16 indices

Array<number>
>= 2 items <= 2 items
original
string
replacement
string
display
string
id
string
location
required
string
url
required
string
protected
required
boolean
followers
required
number
following
required
number
statuses
required
number
media_count
required
number
likes
required
number
joined
required
string
website
required
object
url
required
string
display_url
required
string
birthday
object
day
number
month
number
year
number
verification
object
verified
required
boolean
type
required
string
nullable
Allowed values: organization government individual
verified_at
string
nullable
identity_verified
boolean
verified_by
string
about_account
object
based_in
string
nullable
location_accurate
boolean
created_country_accurate
boolean
nullable
source
string
nullable
username_changes
object
count
required
number
last_changed_at
required
string
nullable
profile_embed
boolean
all
Array
Any of:
object
id
string
format
string
type
required
string
Allowed values: photo gif
url
required
string
width
required
number
height
required
number
transcode_url
string
nullable
altText
string
mosaic
object
id
string
format
string
type
required
string
Allowed values: mosaic_photo
url
required
string
width
required
number
height
required
number
formats
required
object
webp
required
string
jpeg
required
string
broadcast
object
url
required
string
width
required
number
height
required
number
state
required
string
Allowed values: LIVE ENDED
broadcaster
required
object
username
required
string
display_name
required
string
id
required
string
stream
object
url
required
string
title
required
string
source
required
string
orientation
required
string
Allowed values: landscape portrait
broadcast_id
required
string
media_id
required
string
media_key
required
string
is_high_latency
required
boolean
thumbnail
required
object
original
required
object
url
required
string
small
object
url
required
string
medium
object
url
required
string
large
object
url
required
string
x_large
object
url
required
string
raw_text
required
object
text
required
string
facets
required
Array<object>
object
type
required

Facet kind: e.g. url, mention, hashtag, bold, media, custom_emoji (Mastodon custom emoji image)

string
indices
required

Start and end UTF-16 indices

Array<number>
>= 2 items <= 2 items
original
string
replacement
string
display
string
id
string
lang
required
string
nullable
translation
object
text
required
string
source_lang
required
string
source_lang_en
required
string
target_lang
required
string
provider
required
string
possibly_sensitive
required
boolean
replying_to
required
object
screen_name
required

Handle or account id used in permalinks (@user on X).

string
status
required

Parent post id (X: snowflake; Bluesky: record key).

string
url

Permalink to the parent post when known.

string
profile_url

Permalink to the parent author profile when known.

string
display_name

Display name of the parent author when known.

string
source
required
string
nullable
embed_card
required
string
Allowed values: tweet summary summary_large_image player
provider
required
string
Allowed values: bluesky
reposted_by
object
id
required
string
name
required
string
screen_name
required
string
avatar_url
string
nullable
url
string
cursor
required
object
top
required
string
nullable
bottom
required
string
nullable
Example 
{
  "results": [
    {
      "type": "status",
      "quote": {
        "type": "tombstone",
        "provider": "twitter",
        "reason": "deleted",
        "author": {
          "type": "profile",
          "verification": {
            "type": "organization"
          }
        }
      },
      "author": {
        "type": "profile",
        "verification": {
          "type": "organization"
        }
      },
      "media": {
        "external": {
          "type": "video"
        },
        "photos": [
          {
            "type": "photo"
          }
        ],
        "videos": [
          {
            "type": "video",
            "formats": [
              {
                "container": "mp4",
                "codec": "h264"
              }
            ],
            "publisher": {
              "type": "profile",
              "verification": {
                "type": "organization"
              }
            }
          }
        ],
        "all": [
          {
            "type": "photo"
          }
        ],
        "mosaic": {
          "type": "mosaic_photo"
        },
        "broadcast": {
          "state": "LIVE",
          "orientation": "landscape"
        }
      },
      "embed_card": "tweet",
      "provider": "bluesky"
    }
  ]
}