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

  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/status/<jobUUID>Check job status
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-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 access
  • twitter-credential-scraper: Authenticated Twitter access
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/v1/search/live/twitter \
    -H "Authorization: Bearer <API_KEY>" \
    -X POST \
    -H "Content-Type: application/json" \
    -d '{
        "type": "twitter-credential-scraper",
        "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/v1/search/live/twitter \
       -H "Authorization: Bearer <API_KEY>" \
       -X POST \
       -H "Content-Type: application/json" \
       -d '{
           "type": "twitter-credential-scraper", 
               "arguments": {
           "type": "searchbyfullarchive",
           "query": "#AI",
           "max_results": 499
           }
       }'

​
Example of searchbyquery or searchbyfullarchive response:

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

Check Job Status

Use the uuid returned from the previous step to check your job status:

curl https://data.masa.ai/api/v1/search/live/twitter/status/<RETURNED_UUID> \
  -H "Authorization: Bearer <API_KEY>"

For example, if your returned UUID was “5a7b9c12-3d4e-5f6g-7h8i-9j0k1l2m3n4o”:

curl https://data.masa.ai/api/v1/search/live/twitter/result/status/5a7b9c12-3d4e-5f6g-7h8i-9j0k1l2m3n4o \
  -H "Authorization: Bearer <API_KEY>"

​
Response:

{
  "status": "processing",  // Job is currently being processed
  "error": ""
}

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
3

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.