/v1/twitter/search/posts
Search Posts
Search public X/Twitter posts by keyword using Google-indexed results, then fetch the post details without a logged-in X account.
| Credit cost | Default: 1 credit 1 credit per successful page, including empty results. Failed requests and terminal cursor replays are not charged. How charges are determinedCost is decided per call, not per endpoint: the same operation can cost different amounts depending on what it returns. A call that fails costs 0 credits. A result served from cache costs 0 credits. `default` is the cost when no rule matches. Rules are evaluated in order and the first whose conditions all hold wins. A `when` condition is one of: `param` (the request parameter is true), `outcome` (the classifier's outcome), `empty` / `nonEmpty` (a response field is empty and absent, or a non-empty array or string), `flag` (a response field is exactly true). A cost of `{ perStartedMinute: n, of: [fields] }` is n x max(1, ceil(seconds / 60)), so even a short result bills at least one minute. |
|---|---|
| Cache support | Not specified in the published contract. |
| Pagination | No explicit pagination metadata in the published contract. Consult the parameters and response fields below. |
Parameters
| Name | Location / required | Schema |
|---|---|---|
queryKeyword or phrase to search for in Google-indexed public X/Twitter posts | query / required |
|
cursorPass the cursor returned by the previous response. Supported page cursors are 1 through 11. A null response cursor means there are no more pages. | query / optional |
|
Request examples
Replace placeholder values and supply your own API key. For operations with a request body, populate the body using the schema above.
cURL
curl --request GET 'https://api.fetchproof.com/v1/twitter/search/posts?query=YOUR_QUERY' \
--header 'x-api-key: YOUR_API_KEY'JavaScript
const response = await fetch("https://api.fetchproof.com/v1/twitter/search/posts?query=YOUR_QUERY", {
method: 'GET',
headers: { 'x-api-key': process.env.FETCHPROOF_API_KEY }
});
console.log(await response.text());Python
import os
import requests
response = requests.get("https://api.fetchproof.com/v1/twitter/search/posts?query=YOUR_QUERY",
headers={"x-api-key": os.environ["FETCHPROOF_API_KEY"]})
print(response.text)Responses
200Success. Envelope: success / credits_remaining / credits_charged.
application/json
object
successrequired
boolean
credits_remainingrequired
integer
credits_chargedrequired
integer
queryrequired
string
postsrequired
array
Array items
object
rest_idrequired
string
urlrequired
string
viewsrequired
object
countrequired
string
staterequired
string
legacyrequired
object
created_atrequired
string
full_textrequired
string
favorite_countrequired
integer
retweet_countrequired
integer
reply_countrequired
integer
quote_countrequired
integer
bookmark_countrequired
integer
bookmarkedoptional
boolean
conversation_id_stroptional
string
display_text_rangeoptional
array
Array items
integer
entitiesoptional
object
mediaoptional
array
Array items
object
additional_media_inforequired
object
monetizablerequired
boolean
display_urlrequired
string
expanded_urlrequired
string
ext_media_availabilityrequired
object
statusrequired
string
id_strrequired
string
indicesrequired
array
Array items
integer
media_keyrequired
string
media_resultsrequired
object
resultrequired
object
media_keyrequired
string
media_url_httpsrequired
string
original_inforequired
object
focus_rectsrequired
array
heightrequired
integer
widthrequired
integer
sizesrequired
object
largerequired
object
hrequired
integer
resizerequired
string
wrequired
integer
mediumrequired
object
hrequired
integer
resizerequired
string
wrequired
integer
smallrequired
object
hrequired
integer
resizerequired
string
wrequired
integer
thumbrequired
object
hrequired
integer
resizerequired
string
wrequired
integer
typerequired
string
urlrequired
string
video_inforequired
object
aspect_ratiorequired
array
Array items
integer
duration_millisrequired
integer
variantsrequired
array
Array items
object
content_typerequired
string
urlrequired
string
bitrateoptional
integer
allow_download_statusoptional
object
allow_downloadrequired
boolean
urlsoptional
array
Array items
object
display_urlrequired
string
expanded_urlrequired
string
indicesrequired
array
Array items
integer
urlrequired
string
extended_entitiesoptional
object
mediarequired
array
Array items
object
additional_media_inforequired
object
monetizablerequired
boolean
display_urlrequired
string
expanded_urlrequired
string
ext_media_availabilityrequired
object
statusrequired
string
id_strrequired
string
indicesrequired
array
Array items
integer
media_keyrequired
string
media_resultsrequired
object
resultrequired
object
media_keyrequired
string
media_url_httpsrequired
string
original_inforequired
object
focus_rectsrequired
array
heightrequired
integer
widthrequired
integer
sizesrequired
object
largerequired
object
hrequired
integer
resizerequired
string
wrequired
integer
mediumrequired
object
hrequired
integer
resizerequired
string
wrequired
integer
smallrequired
object
hrequired
integer
resizerequired
string
wrequired
integer
thumbrequired
object
hrequired
integer
resizerequired
string
wrequired
integer
typerequired
string
urlrequired
string
video_inforequired
object
aspect_ratiorequired
array
Array items
integer
duration_millisrequired
integer
variantsrequired
array
Array items
object
content_typerequired
string
urlrequired
string
bitrateoptional
integer
allow_download_statusoptional
object
allow_downloadrequired
boolean
favoritedoptional
boolean
id_stroptional
string
is_quote_statusoptional
boolean
langoptional
string
possibly_sensitiveoptional
boolean
possibly_sensitive_editableoptional
boolean
retweetedoptional
boolean
user_id_stroptional
string
__typenameoptional
string
coreoptional
object
user_resultsrequired
object
resultrequired
object
__typenamerequired
string
affiliates_highlighted_labelrequired
object
avatarrequired
object
image_urlrequired
string
corerequired
object
created_atrequired
string
namerequired
string
screen_namerequired
string
dm_permissionsrequired
object
can_dmrequired
boolean
follow_request_sentrequired
boolean
has_graduated_accessrequired
boolean
idrequired
string
is_blue_verifiedrequired
boolean
legacyrequired
object
default_profilerequired
boolean
default_profile_imagerequired
boolean
descriptionrequired
string
entitiesrequired
object
descriptionrequired
object
urlsrequired
array
Array items
object
display_urlrequired
string
expanded_urlrequired
string
indicesrequired
array
Array items
integer
urlrequired
string
urlrequired
object
urlsrequired
array
Array items
object
display_urlrequired
string
expanded_urlrequired
string
indicesrequired
array
Array items
integer
urlrequired
string
fast_followers_countrequired
integer
favourites_countrequired
integer
follow_request_sentrequired
boolean
followers_countrequired
integer
friends_countrequired
integer
has_custom_timelinesrequired
boolean
is_translatorrequired
boolean
listed_countrequired
integer
media_countrequired
integer
needs_phone_verificationrequired
boolean
normal_followers_countrequired
integer
notificationsrequired
boolean
pinned_tweet_ids_strrequired
array
Array items
string
possibly_sensitiverequired
boolean
profile_banner_urlrequired
string
profile_interstitial_typerequired
string
statuses_countrequired
integer
time_zonerequired
string
translator_typerequired
string
urlrequired
string
utc_offsetrequired
integer
withheld_descriptionrequired
string
withheld_scoperequired
string
locationrequired
object
locationrequired
string
media_permissionsrequired
object
can_media_tagrequired
boolean
parody_commentary_fan_labelrequired
string
privacyrequired
object
protectedrequired
boolean
profile_biorequired
object
descriptionrequired
string
profile_description_languagerequired
string
profile_image_shaperequired
string
relationship_perspectivesrequired
object
blocked_byrequired
boolean
blockingrequired
boolean
followed_byrequired
boolean
followingrequired
boolean
mutingrequired
boolean
rest_idrequired
string
super_follow_eligiblerequired
boolean
super_followed_byrequired
boolean
super_followingrequired
boolean
verificationrequired
object
verifiedrequired
boolean
verified_typerequired
string
edit_controloptional
object
edit_tweet_idsoptional
array
Array items
string
editable_until_msecsoptional
string
edits_remainingoptional
string
is_edit_eligibleoptional
boolean
edit_control_initialoptional
object
edit_tweet_idsrequired
array
Array items
string
editable_until_msecsrequired
string
edits_remainingrequired
string
is_edit_eligiblerequired
boolean
initial_tweet_idoptional
string
grok_analysis_buttonoptional
boolean
grok_annotationsoptional
object
is_image_editable_by_grokrequired
boolean
is_translatableoptional
boolean
unmention_dataoptional
object
cardoptional
object
legacyrequired
object
binding_valuesrequired
array
Array items
object
keyrequired
string
valuerequired
object
image_valueoptional
object
altrequired
string
heightrequired
integer
urlrequired
string
widthrequired
integer
typerequired
string
string_valueoptional
string
scribe_keyoptional
string
user_valueoptional
object
id_strrequired
string
pathrequired
array
card_platformrequired
object
platformrequired
object
audiencerequired
object
namerequired
string
devicerequired
object
namerequired
string
versionrequired
string
namerequired
string
urlrequired
string
user_refs_resultsrequired
array
Array items
object
resultrequired
object
__typenamerequired
string
affiliates_highlighted_labelrequired
object
avatarrequired
object
image_urlrequired
string
corerequired
object
created_atrequired
string
namerequired
string
screen_namerequired
string
dm_permissionsrequired
object
can_dmrequired
boolean
follow_request_sentrequired
boolean
has_graduated_accessrequired
boolean
idrequired
string
is_blue_verifiedrequired
boolean
legacyrequired
object
default_profilerequired
boolean
default_profile_imagerequired
boolean
descriptionrequired
string
entitiesrequired
object
descriptionrequired
object
urlsrequired
array
Array items
object
display_urlrequired
string
expanded_urlrequired
string
indicesrequired
array
Array items
integer
urlrequired
string
urlrequired
object
urlsrequired
array
Array items
object
display_urlrequired
string
expanded_urlrequired
string
indicesrequired
array
Array items
integer
urlrequired
string
fast_followers_countrequired
integer
favourites_countrequired
integer
follow_request_sentrequired
boolean
followers_countrequired
integer
friends_countrequired
integer
has_custom_timelinesrequired
boolean
is_translatorrequired
boolean
listed_countrequired
integer
media_countrequired
integer
needs_phone_verificationrequired
boolean
normal_followers_countrequired
integer
notificationsrequired
boolean
pinned_tweet_ids_strrequired
array
Array items
string
possibly_sensitiverequired
boolean
profile_banner_urlrequired
string
profile_interstitial_typerequired
string
statuses_countrequired
integer
time_zonerequired
string
translator_typerequired
string
urlrequired
string
utc_offsetrequired
integer
withheld_descriptionrequired
string
withheld_scoperequired
string
locationrequired
object
locationrequired
string
media_permissionsrequired
object
can_media_tagrequired
boolean
parody_commentary_fan_labelrequired
string
privacyrequired
object
protectedrequired
boolean
profile_biorequired
object
descriptionrequired
string
profile_description_languagerequired
string
profile_image_shaperequired
string
relationship_perspectivesrequired
object
blocked_byrequired
boolean
blockingrequired
boolean
followed_byrequired
boolean
followingrequired
boolean
mutingrequired
boolean
rest_idrequired
string
super_follow_eligiblerequired
boolean
super_followed_byrequired
boolean
super_followingrequired
boolean
verificationrequired
object
verifiedrequired
boolean
verified_typerequired
string
rest_idrequired
string
note_tweetoptional
object
is_expandablerequired
boolean
note_tweet_resultsrequired
object
resultrequired
object
entity_setrequired
object
hashtagsrequired
array
symbolsrequired
array
urlsrequired
array
Array items
object
display_urlrequired
string
expanded_urlrequired
string
indicesrequired
array
Array items
integer
urlrequired
string
user_mentionsrequired
array
timestampsoptional
array
idrequired
string
richtextrequired
object
richtext_tagsrequired
array
textrequired
string
previous_countsoptional
object
bookmark_countrequired
integer
favorite_countrequired
integer
quote_countrequired
integer
reply_countrequired
integer
retweet_countrequired
integer
content_disclosureoptional
object
ai_generated_disclosurerequired
object
ai_generated_detection_sourcerequired
string
can_editrequired
boolean
has_ai_generated_mediarequired
boolean
cursorrequired
string