> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sociavault.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Search
> Search Twitter for tweets, users, photos, media, and more. Results are paginated — use the cursor parameter to fetch additional pages.
💳 **1 credit** per request
## OpenAPI
````yaml GET /v1/scrape/twitter/search
openapi: 3.1.0
info:
title: SociaVault API
version: 1.0.0
description: >-
# SociaVault API Documentation
The SociaVault API provides comprehensive access to social media data
extraction across multiple platforms.
## Features
- **Multi-Platform Support**: TikTok, Instagram, YouTube, Facebook, Twitter,
Reddit, Threads, and more
- **Credit-Based System**: Pay-as-you-go pricing with transparent credit
costs
- **High Performance**: Fast, reliable data extraction
- **Comprehensive Data**: Detailed user profiles, videos, posts, comments,
and analytics
## Authentication
All API requests require authentication using an API key in the `X-API-Key`
header:
```bash
X-API-Key: sk_live_your_api_key_here
```
Get your API key from the [SociaVault
Dashboard](https://sociavault.com/dashboard).
## Credits
Each endpoint consumes credits based on data complexity:
- Simple requests (profiles): 1 credit
- Complex requests (demographics): 20+ credits
- Paginated requests: Credits per page
Check your credit balance in the dashboard or via the API.
## Support
- **Documentation**: https://docs.sociavault.com
- **Email**: support@sociavault.com
- **Discord**: https://discord.gg/sociavault
contact:
name: SociaVault Support
email: support@sociavault.com
url: https://sociavault.com/support
license:
name: Commercial
url: https://sociavault.com/terms
servers:
- url: https://api.sociavault.com
description: Production API
security:
- ApiKeyAuth: []
tags:
- name: account
description: Account management and credit balance
externalDocs:
description: Learn more
url: https://docs.sociavault.com/account
- name: tiktok
description: Scrape TikTok profiles, videos, and more
externalDocs:
description: Learn more
url: https://docs.sociavault.com/platforms/tiktok
- name: tiktok-shop
description: Everything about TikTok Shop
externalDocs:
description: Learn more
url: https://docs.sociavault.com/platforms/tiktok-shop
- name: instagram
description: Gets Instagram profiles, posts, and reels
externalDocs:
description: Learn more
url: https://docs.sociavault.com/platforms/instagram
- name: youtube
description: Scrape YouTube channels, videos, and more
externalDocs:
description: Learn more
url: https://docs.sociavault.com/platforms/youtube
- name: linkedin
description: Scrape LinkedIn
externalDocs:
description: Learn more
url: https://docs.sociavault.com/platforms/linkedin
- name: facebook
description: Get public Facebook profiles and posts
externalDocs:
description: Learn more
url: https://docs.sociavault.com/platforms/facebook
- name: facebookAdLibrary
description: Scrapes the Facebook (Meta) Ad Library
externalDocs:
description: Learn more
url: https://docs.sociavault.com/platforms/facebookAdLibrary
- name: facebookMarketplace
description: Search Facebook Marketplace and pull full listing details
externalDocs:
description: Learn more
url: https://docs.sociavault.com/platforms/facebookMarketplace
- name: googleAdLibrary
description: >-
Scrape the Google Ad Transparency Library. *This only gets the public ads.
Some ads you need to log in for and sadly we can't get those. Also, since
there are so many variations, the return types might not all be 100% the
same.
externalDocs:
description: Learn more
url: https://docs.sociavault.com/platforms/googleAdLibrary
- name: linkedinAdLibrary
description: Search the LinkedIn Ad Library
externalDocs:
description: Learn more
url: https://docs.sociavault.com/platforms/linkedinAdLibrary
- name: twitter
description: Get Twitter profiles, tweets, followers and more
externalDocs:
description: Learn more
url: https://docs.sociavault.com/platforms/twitter
- name: reddit
description: Scrape Reddit posts and comments
externalDocs:
description: Learn more
url: https://docs.sociavault.com/platforms/reddit
- name: threads
description: Get Threads posts
externalDocs:
description: Learn more
url: https://docs.sociavault.com/platforms/threads
- name: google
description: Scrape Google search results
externalDocs:
description: Learn more
url: https://docs.sociavault.com/platforms/google
paths:
/v1/scrape/twitter/search:
get:
tags:
- twitter
summary: Search
description: >-
Search Twitter for tweets, users, photos, media, and more. Results are
paginated — use the cursor parameter to fetch additional pages.
operationId: twitter_Search
parameters:
- name: query
in: query
description: The search query text
required: true
schema:
type: string
example: AI
- name: type
in: query
description: >-
The type of search results to return. Defaults to Top if not
provided.
required: false
schema:
type: string
enum:
- Top
- Latest
- People
- Photos
- Media
- Lists
default: Top
example: Top
- name: cursor
in: query
description: >-
Pagination cursor from a previous response to get the next page of
results
required: false
schema:
type: string
responses:
'200':
description: >-
Successful response
**Key Response Fields:**
**Pagination:**
- `has_more`: `false` when this page returned no results — the
signal to stop paginating (keep paging while `true`)
- `result_count`: Number of results (tweets or users) on this page
- `data.cursor.bottom`: Pass as `cursor` query param to get the next
page of results
- `data.cursor.top`: Cursor for the previous/newer page
**Search Results (type=Top):**
- `data.result.timeline.instructions[0].entries[]`: Array of result
entries (type `TimelineAddEntries`)
**People Carousel** (first entry when type=Top):
- `entries[0].content.items[]`: Array of matched user profiles
displayed in a carousel
- `entries[0].content.header.text`: Will be `People`
- Each user at `.item.itemContent.user_results.result`:
- `.rest_id`: User's numeric ID
- `.is_blue_verified`: Blue checkmark status
- `.legacy.name`: Display name
- `.legacy.screen_name`: Handle (username without @)
- `.legacy.description`: Bio
- `.legacy.followers_count`: Follower count
- `.legacy.friends_count`: Following count
- `.legacy.profile_image_url_https`: Profile picture URL
- `.legacy.verified_type`: `Business` for business accounts
**Tweet Results** (subsequent entries):
- Each tweet at
`entries[].content.itemContent.tweet_results.result`:
- `.rest_id`: Tweet ID
- `.legacy.full_text`: Tweet text
- `.legacy.created_at`: Timestamp
- `.views.count`: View count (string)
- `.legacy.favorite_count`: Likes
- `.legacy.retweet_count`: Retweets
- `.legacy.reply_count`: Replies
- `.legacy.quote_count`: Quote tweets
- `.legacy.bookmark_count`: Bookmarks
**Feedback Actions:**
- `data.result.timeline.responseObjects.feedbackActions[]`: Internal
feedback metadata (can ignore)
content:
application/json:
examples:
trimmed:
summary: Trimmed Response
value:
success: true
data:
error: false
cursor:
bottom: >-
DAACCgACHPoex7FAJxAKAAMc-h7HsT_Y8AgABAAAAAILAAUAAADwRW1QQzZ3QUFBZlEvZ0dKTjB2R3AvQUFBQUJRYytkZVBoRmJBNWh6NkNIcksya0FWSFBqbStJcWFzR01jOUl0d1lCZXdYaHo2RGlNMGw3RFVIUG5kMUd1V0lad2M5MkJZdEZ2UmNCejUzWVpLMmhBdkhQbWpKRVFYSUdVYzhqOWd6aGRnQ0J6NkIrRjFGNUZwSFBhZEhvMGE4UThjK1p4WCtGcnd1Qno1KytiZzFxRy9IUG00dGdqV1FKRWM5SXNFSVZaQWZoejU2SXlIVjJIT0hQbkdnM2FYMFJjYytYTWt1WnR3dlJ6dzFqQ3dWbEJJCAAGAAAAAAgABwAAAAAMAAgKAAEc8NYwsFZQSAAAAA
top: >-
DAACCgACHPoex7FAJxAKAAMc-h7HsT_Y8AgABAAAAAELAAUAAADwRW1QQzZ3QUFBZlEvZ0dKTjB2R3AvQUFBQUJRYytkZVBoRmJBNWh6NkNIcksya0FWSFBqbStJcWFzR01jOUl0d1lCZXdYaHo2RGlNMGw3RFVIUG5kMUd1V0lad2M5MkJZdEZ2UmNCejUzWVpLMmhBdkhQbWpKRVFYSUdVYzhqOWd6aGRnQ0J6NkIrRjFGNUZwSFBhZEhvMGE4UThjK1p4WCtGcnd1Qno1KytiZzFxRy9IUG00dGdqV1FKRWM5SXNFSVZaQWZoejU2SXlIVjJIT0hQbkdnM2FYMFJjYytYTWt1WnR3dlJ6dzFqQ3dWbEJJCAAGAAAAAAgABwAAAAAMAAgKAAEc8NYwsFZQSAAAAA
result:
timeline:
instructions:
- entries:
- content:
__typename: TimelineTimelineItem
clientEventInfo:
component: result
details:
timelinesDetails:
controllerData: >-
DAACDAAFDAABDAABDAABCgABAAAAAgACAAAAAAwAAgoAAQAAAAAAAAABCgAC+ELhsGrQNBsLAAMAAAAHYml0Y29pbgoABRqkE5BWnflTCAAGAAAAAQoAByvFVhCRM6XfCgAIAAABn/0IIWwAAAAAAA==
element: tweet
entryType: TimelineTimelineItem
feedbackInfo:
feedbackKeys:
- '-2134788070'
itemContent:
__typename: TimelineTweet
highlights:
textHighlights:
- endIndex: 71
startIndex: 64
itemType: TimelineTweet
tweetDisplayType: Tweet
tweet_results:
result:
__typename: Tweet
core:
user_results:
result:
__typename: User
affiliates_highlighted_label: {}
has_graduated_access: true
id: VXNlcjoxMzcyNTY4MTg3MTM3NjM0MzEy
is_blue_verified: true
legacy:
blocked_by: false
blocking: false
can_dm: true
can_media_tag: true
created_at: Thu Mar 18 15:19:45 +0000 2021
default_profile: true
default_profile_image: false
description: >-
Explicando #Bitcoin e ajudando
investidores a construir patrimônio com
dinheiro descentralizado.
Head Research @formadores_edu,
Embaixador @InsilicoTrading.
entities:
description: {}
url:
urls:
- display_url: linktr.ee/caueconomy
expanded_url: https://linktr.ee/caueconomy
indices:
- 0
- 23
url: https://t.co/7k4skWu6xI
fast_followers_count: 0
favourites_count: 47342
follow_request_sent: false
followed_by: false
followers_count: 32745
following: false
friends_count: 1581
has_custom_timelines: true
is_translator: false
listed_count: 351
location: ''
media_count: 7148
muting: false
name: Cauê Oliveira
needs_phone_verification: false
normal_followers_count: 32745
notifications: false
possibly_sensitive: false
profile_banner_url: >-
https://pbs.twimg.com/profile_banners/1372568187137634312/1750153422
profile_image_url_https: >-
https://pbs.twimg.com/profile_images/1440970906923376642/6M-gRDjG_normal.jpg
profile_interstitial_type: ''
protected: false
screen_name: caueconomy
statuses_count: 22144
time_zone: ''
translator_type: none
url: https://t.co/7k4skWu6xI
utc_offset: 0
verified: false
want_retweets: false
withheld_description: ''
withheld_scope: ''
professional:
category: []
professional_type: Creator
rest_id: '1502245534899355653'
profile_image_shape: Circle
rest_id: '1372568187137634312'
super_follow_eligible: false
super_followed_by: false
super_following: false
tipjar_settings:
bitcoin_handle: 3JojAaytVMsrTbGTa2wG2W8e2TE2YqNL7v
is_enabled: true
edit_control:
edit_tweet_ids:
- '2087955592526651854'
editable_until_msecs: '1786645980000'
edits_remaining: '5'
is_edit_eligible: true
is_translatable: true
legacy:
bookmark_count: 12
bookmarked: false
conversation_id_str: '2087955592526651854'
created_at: Thu Aug 13 17:33:00 +0000 2026
display_text_range:
- 0
- 279
entities:
media:
- allow_download_status:
allow_download: true
display_url: pic.x.com/fwErZlcTQO
expanded_url: >-
https://x.com/caueconomy/status/2087955592526651854/photo/1
ext_media_availability:
status: Available
features:
large:
faces: []
medium:
faces: []
orig:
faces: []
small:
faces: []
id_str: '2087933519326560257'
indices:
- 280
- 303
media_key: 3_2087933519326560257
media_results:
result:
media_key: 3_2087933519326560257
media_url_https: >-
https://pbs.twimg.com/media/HPnUeTYXQAE2fzq.jpg
original_info:
focus_rects:
- h: 634
w: 1132
x: 0
'y': 188
- h: 822
w: 822
x: 155
'y': 0
- h: 822
w: 721
x: 206
'y': 0
- h: 822
w: 411
x: 361
'y': 0
- h: 822
w: 1132
x: 0
'y': 0
height: 822
width: 1132
sizes:
large:
h: 822
resize: fit
w: 1132
medium:
h: 822
resize: fit
w: 1132
small:
h: 494
resize: fit
w: 680
thumb:
h: 150
resize: crop
w: 150
type: photo
url: https://t.co/fwErZlcTQO
extended_entities:
media:
- allow_download_status:
allow_download: true
display_url: pic.x.com/fwErZlcTQO
expanded_url: >-
https://x.com/caueconomy/status/2087955592526651854/photo/1
ext_media_availability:
status: Available
features:
large:
faces: []
medium:
faces: []
orig:
faces: []
small:
faces: []
id_str: '2087933519326560257'
indices:
- 280
- 303
media_key: 3_2087933519326560257
media_results:
result:
media_key: 3_2087933519326560257
media_url_https: >-
https://pbs.twimg.com/media/HPnUeTYXQAE2fzq.jpg
original_info:
focus_rects:
- h: 634
w: 1132
x: 0
'y': 188
- h: 822
w: 822
x: 155
'y': 0
- h: 822
w: 721
x: 206
'y': 0
- h: 822
w: 411
x: 361
'y': 0
- h: 822
w: 1132
x: 0
'y': 0
height: 822
width: 1132
sizes:
large:
h: 822
resize: fit
w: 1132
medium:
h: 822
resize: fit
w: 1132
small:
h: 494
resize: fit
w: 680
thumb:
h: 150
resize: crop
w: 150
type: photo
url: https://t.co/fwErZlcTQO
favorite_count: 150
favorited: false
full_text: >-
Alguém pagou 1,6 BTC ($102 mil) em taxa
para não enviar nada de bitcoin.🚨
A transação "comeu" todo o saldo da
transação fazendo com que essa tenha
sido uma transação que pagou 39 MIL
VEZES de excesso.
A causa foi um bug no RBF
(Replace-by-Fee) ativado, aumentando a
fee sozinho https://t.co/fwErZlcTQO
id_str: '2087955592526651854'
is_quote_status: false
lang: pt
possibly_sensitive: false
possibly_sensitive_editable: true
quote_count: 5
reply_count: 23
retweet_count: 8
retweeted: false
user_id_str: '1372568187137634312'
note_tweet:
is_expandable: true
note_tweet_results:
result:
entity_set:
hashtags: []
symbols: []
urls: []
user_mentions: []
id: Tm90ZVR3ZWV0OjIwODc5NTU1OTI0NTk1MzAyNDA=
richtext:
richtext_tags:
- from_index: 0
richtext_types:
- Bold
to_index: 74
text: >-
Alguém pagou 1,6 BTC ($102 mil) em taxa
para não enviar nada de bitcoin.🚨
A transação "comeu" todo o saldo da
transação fazendo com que essa tenha
sido uma transação que pagou 39 MIL
VEZES de excesso.
A causa foi um bug no RBF
(Replace-by-Fee) ativado, aumentando a
fee sozinho a cada tentativa por cerca
de 29 minutos direto, até devorar os 1,6
BTC inteiros da carteira.
Um dos erros mais caros que já vi na
rede.
rest_id: '2087955592526651854'
source: >-
Twitter Web Client
unmention_data: {}
views:
count: '10051'
state: EnabledWithCount
entryId: tweet-2087955592526651854
sortIndex: '2088015220260732928'
type: TimelineAddEntries
responseObjects:
feedbackActions:
- key: '-2134788070'
value:
childKeys:
- '269351462'
- '-1399782652'
clientEventInfo:
action: click
component: result
element: feedback_givefeedback
confirmation: >-
Thanks for offering your feedback. X is
conducting research to improve search.
Choose the option that best reflects your
opinion.
confirmationDisplayType: Inline
feedbackType: GiveFeedback
hasUndoAction: true
icon: Frown
prompt: This post's not helpful
- key: '269351462'
value:
clientEventInfo:
action: click
component: result
element: feedback_notrelevant
confirmation: >-
Thanks for your help.
This feedback will be used in research to
improve the search function.
confirmationDisplayType: Inline
feedbackType: NotRelevant
hasUndoAction: true
prompt: This post isn't relevant
result_count: 20
has_more: true
credits_used: 1
endpoint: twitter/search
'400':
description: Bad Request - Invalid parameters or missing required fields
content:
application/json:
schema:
type: object
properties:
error:
type: string
example: query is required
endpoint:
type: string
credits_required:
type: integer
required:
- error
'401':
description: Unauthorized - Invalid or missing API key
content:
application/json:
schema:
type: object
properties:
error:
type: string
example: Invalid API key
docs:
type: string
example: https://docs.sociavault.com/authentication
required:
- error
'402':
description: Payment Required - Insufficient credits
content:
application/json:
schema:
type: object
properties:
error:
type: string
example: Insufficient credits
required:
type: integer
example: 1
description: Credits required for this request
available:
type: integer
example: 0
description: Credits currently available
required:
- error
- required
- available
'500':
description: Internal Server Error
content:
application/json:
schema:
type: object
properties:
error:
type: string
example: Failed to search Twitter
endpoint:
type: string
example: search
required:
- error
components:
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: X-API-Key
description: |-
API key for authentication. Format: `sk_live_xxxxxxxxxxxxx`
Get your API key from the [Dashboard](https://sociavault.com/dashboard).
````
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.