​
Scrape Real-time & Historical Data

Search and retrieve X/Twitter content in real-time or access historical data through our secure API.

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:
  1. Visit the Data API Dashboard
  2. Sign up for an account with GitHub
  3. Automatically receive an API key
  4. Start searching X/Twitter data in real-time and historical data.
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:
MethodEndpointDescription
POST/v1/search/live/twitterSubmit a Twitter search
GET/v1/search/live/twitter/result/<jobUUID>Get search results

​
Authentication

  • Type: Bearer Token
  • Header: Authorization: Bearer <API_KEY>
Please note that the API is currently in active development. You may occasionally need to rerun jobs as we make improvements and updates to the system.

​
X/Twitter search workflows

1

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-credential: Twitter scraping with credentials
    • Supports: searchbyquery, searchbyfullarchive, searchbyprofile, getbyid, getreplies, getretweeters, gettweets, getmedia, gethometweets, getforyoutweets, getprofilebyid, gettrends, getfollowing, getfollowers, getspace
  • twitter-api: Twitter scraping with API keys
    • Supports: searchbyquery, getbyid, getprofilebyid (basic), plus searchbyfullarchive
  • twitter: General Twitter scraping (uses best available auth)
    • Sub-capabilities: Dynamic based on available authentication
Each data source type includes different search methods. Please see the examples below for more details.

​
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 data
  • searchbyfullarchive: 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 or twitter-api-scraper type.
  • max_results determines how many tweets to return (up to 100 per request).

​
Using searchbyquery to search live X/Twitter data


    curl https://data.masa.ai/api/v1/search/live/twitter \
    -H "Authorization: Bearer <API KEY>" \
    -X POST \
    -H "Content-Type: application/json" \
    -d '{
    "type": "twitter",
    "arguments": {
      "type": "searchbyquery",
      "query": "#AI",
      "max_results": 10
      }
    }'
Type can be “twitter-scraper”, “twitter-api-scraper”, or “twitter-credential-scraper”

​
Using searchbyfullarchive to search historical tweets

  • max_results determines how many tweets to return (up to 500 per request).
       curl https://data.masa.ai/api/v1/search/live/twitter \
       -H "Authorization: Bearer <API KEY>" \
       -X POST \
       -H "Content-Type: application/json" \
       -d '{
       "type": "twitter",
       "arguments": {
         "type": "searchbyfullarchive",
         "query": "#bitcoin",
         "max_results": 499
         }
       }'

​
Example of searchbyquery or searchbyfullarchive response:

{
  "uuid": "5a7b9c12-3d4e-5f6g-7h8i-9j0k1l2m3n4o",
  "error": ""
}
2

Retrieve Results

Once the job status shows “done”, use your UUID to retrieve the search results:
curl https://data.masa.ai/api/v1/search/live/twitter/result/<RETURNED_UUID> \
    -H "Authorization: Bearer <API_KEY>"

​
Response:

[
{
"ID": "456013170523684434",
"Content": "Bitcoin($BTC) going to $100k soon 😎",
"Metadata": null,
"Score": 1
}
]
The Metadata field is currently null. Near future release will include metadata for each tweet.

​
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.