X/Twitter Live Search & Historical Data
Live Search & Historical Data
The live search endpoint enables real-time search and retrieval of X/Twitter content through our TEE-secured API. This endpoint provides:
Real-time & Historical
Access both recent tweets in near real-time and historical archived content
Secure & Rate-Limited
Protected data retrieval through TEE nodes with 3 requests/second rate limiting
Advanced Queries
Support for complex search queries and filters to find exactly what you need
Structured Data
All results delivered in clean, structured JSON format for easy integration
The live search functionality is ideal for AI agents and applications that require real-time X/Twitter data.
To get started with the Masa Data API:
- Visit the Data API Dashboard
- Sign up for an account with GitHub
- Automatically receive an API key
- Start searching X/Twitter data in real-time and historical data.
Twitter Search
The Twitter Search API allows you to search and retrieve tweets based on keywords, hashtags, and other criteria. The search functionality provides:
- Real-time Results: Get the latest tweets matching your search criteria
- Flexible Queries: Search by keywords, hashtags, mentions, and more
- Rate Limited: 10 requests per minute per API key
- Structured Data: Results include tweet text, metadata, and engagement metrics
Key endpoints:
Method | Endpoint | Description |
---|---|---|
POST | /v1/search/live/twitter | Submit a Twitter search |
GET | /v1/search/live/twitter/status/<jobUUID> | Check job status |
GET | /v1/search/live/twitter/result/<jobUUID> | Get search results |
Authentication
- Type: Bearer Token
- Header:
Authorization: Bearer <API_KEY>
X/Twitter search workflows
Understanding X/Twitter Search Types and Methods
Data source types and available endpoints
Different data source types provide varying levels of access to X/Twitter data. Choose the appropriate type based on your search needs:
Submit a search request to our data API. The endpoint accepts different data source types:
twitter-scraper
: Default search type that automatically selects between credential or API key access, prioritizing credentials if available and falling back to API key access if not.twitter-api-scraper
: Twitter API level accesstwitter-credential-scraper
: Authenticated Twitter access
Search methods type
live or historical data
For each source type, you can specify the search method to search live or historical data:
searchbyquery
: Search live X/Twitter datasearchbyfullarchive
: Search historical tweets available via the
Example requests:
- Base API endpoint:
/v1/search/live/twitter
- Replace
<API_KEY>
with your provided API key - Advanced Twitter search operators (e.g., “from:user”, “since:YYYY-MM-DD”) when utilizing the
twitter-scraper
ortwitter-api-scraper
type. - max_results determines how many tweets to return (up to 100 per request).
Using searchbyquery
to search live X/Twitter data
Using searchbyfullarchive
to search historical tweets
- max_results determines how many tweets to return (up to 500 per request).
Example of searchbyquery
or searchbyfullarchive
response:
Check Job Status
Use the uuid
returned from the previous step to check your job status:
For example, if your returned UUID was “5a7b9c12-3d4e-5f6g-7h8i-9j0k1l2m3n4o”:
Response:
The status field can be one of:
"processing"
: Job is actively being processed"done"
: Job completed successfully"error"
: Job failed with an error"error(retrying)"
: Job failed but system is automatically retrying
Retrieve Results
Once the job status shows “done”, use your UUID to retrieve the search results:
Response:
Advances search X/Twitter API
For advanced search API documentation, please see the Masa protocol X/Twitter advanced search documentation. Please note that the API is currently in active development and the documentation is subject to change.