# Social Fetch API - X / Twitter endpoints
# Base URL: https://api.socialfetch.dev
# Auth: x-api-key header (sfk_...)
# Full catalog: https://www.socialfetch.dev/llms-endpoints.txt | JSON: https://www.socialfetch.dev/llms.json
# Docs hub: https://www.socialfetch.dev/docs/api | OpenAPI: https://www.socialfetch.dev/openapi.json

9 documented X / Twitter operations. Do not invent paths - only the routes below (and their linked markdown pages) are supported.

## GET /v1/twitter/profiles/{handle}
Get Twitter profile
Credit cost: 1 credit per successful request.
Docs: https://www.socialfetch.dev/docs/api/v1/twitter/profiles/handle/get.mdx
SDK: client.twitter.getProfile({ handle })
Parameters:
- handle (required, string) - X handle to look up, with or without a leading @.
Outcome field: `data.lookupStatus` in `found`, `private`, `not_found`
curl "https://api.socialfetch.dev/v1/twitter/profiles/charlidamelio" \
  -H "x-api-key: YOUR_API_KEY"

## GET /v1/twitter/profiles/{handle}/tweets
List Twitter profile tweets
Credit cost: 2 credits per successful request.
Docs: https://www.socialfetch.dev/docs/api/v1/twitter/profiles/handle/tweets/get.mdx
SDK: client.twitter.getProfileTweets({ handle: "elonmusk" })
Parameters:
- handle (required, string) - X handle to look up, with or without a leading @.
- limit (optional) - Optional page size. Defaults to 40 when omitted. Maximum supported value is 100.
- cursor (optional, string) - Opaque pagination cursor returned by a previous response.
- includeReplies (optional) - Optional: include reply tweets in the returned list. Defaults to false.
- includePinned (optional) - Optional: include pinned tweets on the first page. Defaults to false.
Pagination: send query `cursor` from prior `data.page.nextCursor`; stop when `data.page.hasMore` is false.
Outcome field: `data.lookupStatus` in `found`, `not_found`
curl "https://api.socialfetch.dev/v1/twitter/profiles/charlidamelio/tweets" \
  -H "x-api-key: YOUR_API_KEY"

## GET /v1/twitter/tweets
Get Twitter tweet
Credit cost: 1 credit per successful request.
Docs: https://www.socialfetch.dev/docs/api/v1/twitter/tweets/get.mdx
SDK: client.twitter.getTweet({ url })
Parameters:
- url (required, string) - Tweet permalink or identifier.
- trim (optional, boolean) - Optional: omit author profile and tweet `core` for a smaller response.
Outcome field: `data.lookupStatus` in `found`, `not_found`
curl "https://api.socialfetch.dev/v1/twitter/tweets?url=https://x.com/elonmusk/status/2044990537145753894" \
  -H "x-api-key: YOUR_API_KEY"

## GET /v1/twitter/tweets/replies
List Twitter tweet replies
Credit cost: 2 credits per successful request.
Docs: https://www.socialfetch.dev/docs/api/v1/twitter/tweets/replies/get.mdx
SDK: client.twitter.listTweetReplies({ url })
Parameters:
- url (required, string) - Tweet permalink or identifier.
- cursor (optional, string) - Opaque pagination cursor returned by a previous response.
Pagination: send query `cursor` from prior `data.page.nextCursor`; stop when `data.page.hasMore` is false.
curl "https://api.socialfetch.dev/v1/twitter/tweets/replies?url=https://x.com/elonmusk/status/2044990537145753894" \
  -H "x-api-key: YOUR_API_KEY"

## GET /v1/twitter/tweets/transcript
Get Twitter tweet transcript
Credit cost: 1 credit per successful request.
Docs: https://www.socialfetch.dev/docs/api/v1/twitter/tweets/transcript/get.mdx
SDK: client.twitter.getTweetTranscript({ url })
Parameters:
- url (required, string) - Tweet permalink or identifier.
Outcome field: `data.lookupStatus` in `found`, `not_found`, `lookup_failed`
Disambiguation: For video tweets only. Responses can take longer than typical lookups. Videos longer than about two minutes cannot be transcribed.
curl "https://api.socialfetch.dev/v1/twitter/tweets/transcript?url=https://x.com/TheoVon/status/1916982720317821050" \
  -H "x-api-key: YOUR_API_KEY"

## GET /v1/twitter/search
Search Twitter posts
Credit cost: 2 credits per successful request.
Docs: https://www.socialfetch.dev/docs/api/v1/twitter/search/get.mdx
SDK: client.twitter.search({ query })
Parameters:
- query (required, string) - Search query text to run against public posts on X.
- section (optional, string, enum: top | latest | people | photos | videos) - Optional search section filter. Omit to use the default `top` section.
- minRetweets (optional) - Optional minimum retweet count filter.
- minLikes (optional) - Optional minimum like count filter.
- minReplies (optional) - Optional minimum reply count filter.
- limit (optional) - Optional page size. Maximum supported value is 20.
- startDate (optional, string) - Optional start date filter in YYYY-MM-DD format.
- endDate (optional, string) - Optional end date filter in YYYY-MM-DD format.
- language (optional, string, enum: en | es | fr | de | it | pt | ru | zh | ja | ko | ar | bg | hr | cs | da | nl | et | fi | el | hu | id | ga | lv | lt | no | pl | ro | sk | sl | sv | tr | uk | vi | cy | zu) - Optional language filter.
- cursor (optional, string) - Opaque pagination cursor returned by a previous response.
Pagination: send query `cursor` from prior `data.page.nextCursor`; stop when `data.page.hasMore` is false.
curl "https://api.socialfetch.dev/v1/twitter/search?query=what to watch this weekend" \
  -H "x-api-key: YOUR_API_KEY"

## GET /v1/twitter/hashtags
Search Twitter by hashtag
Credit cost: 2 credits per successful request.
Docs: https://www.socialfetch.dev/docs/api/v1/twitter/hashtags/get.mdx
SDK: client.twitter.searchHashtags({ hashtag: "python" })
Parameters:
- hashtag (required, string) - Hashtag to search for.
- section (optional, string, enum: top | latest | people | photos | videos) - Optional section filter for the hashtag feed. Omit to use the default `top` section.
- limit (optional) - Optional page size. Maximum supported value is 20.
- cursor (optional, string) - Opaque pagination cursor returned by a previous response.
Pagination: send query `cursor` from prior `data.page.nextCursor`; stop when `data.page.hasMore` is false.
curl "https://api.socialfetch.dev/v1/twitter/hashtags?hashtag=#trending" \
  -H "x-api-key: YOUR_API_KEY"

## GET /v1/twitter/communities
Get Twitter community
Credit cost: 1 credit per successful request.
Docs: https://www.socialfetch.dev/docs/api/v1/twitter/communities/get.mdx
SDK: client.twitter.getCommunity({ url })
Parameters:
- url (required, string) - Community URL to look up.
Outcome field: `data.lookupStatus` in `found`, `not_found`
curl "https://api.socialfetch.dev/v1/twitter/communities?url=https://x.com/elonmusk/status/2044990537145753894" \
  -H "x-api-key: YOUR_API_KEY"

## GET /v1/twitter/communities/tweets
List Twitter community tweets
Credit cost: 1 credit per successful request.
Docs: https://www.socialfetch.dev/docs/api/v1/twitter/communities/tweets/get.mdx
SDK: client.twitter.getCommunityTweets({ url })
Parameters:
- url (required, string) - Community URL to look up.
Outcome field: `data.lookupStatus` in `found`, `not_found`
Empty results: `lookupStatus: found` may still return an empty `data.tweets` array.
curl "https://api.socialfetch.dev/v1/twitter/communities/tweets?url=https://x.com/elonmusk/status/2044990537145753894" \
  -H "x-api-key: YOUR_API_KEY"