X Search

The Basic X Search API allows users to search for relevant links or tweets based on X search queries without leveraging AI-powered models. This API analyzes links from X posts that match the given prompt.

Using X Posts Search API

The following examples demonstrate how to interact with the Basic X Search API using multiple coding platforms.

Request Sample

The below code snippet script:

Interacts with the Desearch AI X API https://api.desearch.ai/twitter to retrieve tweets related to the keyword "Bittensor" within a specified date range.
The code then sends a POST request with a structured JSON payload containing search query, sort and count
The API request is authenticated via an authorization key, and upon execution, the script prints the HTTP response status code along with the JSON-formatted search results.

python

import requests

url = "https://api.desearch.ai/twitter"
headers = {
    "Authorization": "<your-api-key>",
    "Content-Type": "application/json"
}

params = {
    "query": "Bittensor",
    "sort": "Top",
    "count": 20
}

response = requests.get(url, params=params, headers=headers)

print(response.status_code)
print(response.json())

javascript

const url = new URL("https://api.desearch.ai/twitter");
const headers = {
  Authorization: "<your-api-key>",
  "Content-Type": "application/json",
};

const params = {
  query: "Bittensor",
  sort: "Top",
  count: 20,
};

// Append query parameters to URL
Object.keys(params).forEach((key) => url.searchParams.append(key, params[key]));

fetch(url, {
  method: "GET",
  headers: headers,
})
  .then((response) => response.json())
  .then((data) => console.log(data))
  .catch((error) => console.error("Error:", error));

node

const axios = require("axios");

const url = "https://api.desearch.ai/twitter";

const headers = {
  Authorization: "<your-api-key>",
  "Content-Type": "application/json",
};

const params = {
  query: "Bittensor",
  sort: "Top",
  count: 20,
};

axios
  .get(url, {
    headers,
    params,
  })
  .then((response) => console.log(response.data))
  .catch((error) =>
    console.error("Error:", error.response?.data || error.message)
  );

php

    <?php

    $url = "https://api.desearch.ai/twitter";
    $headers = [
        "Authorization: <your-api-key>",
        "Content-Type: application/json"
    ];

    $params = [
        "query" => "Bittensor",
        "sort" => "Top",
        "count" => 10
    ];

    // Build query string
    $queryString = http_build_query($params);

    // Final URL with query parameters
    $fullUrl = $url . '?' . $queryString;

    $ch = curl_init();

    curl_setopt($ch, CURLOPT_URL, $fullUrl);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);

    $response = curl_exec($ch);
    curl_close($ch);

    echo $response;
    ?>

swift

    import Foundation

    var components = URLComponents(string: "https://api.desearch.ai/twitter")!

    components.queryItems = [
        URLQueryItem(name: "query", value: "Bittensor"),
        URLQueryItem(name: "sort", value: "Top"),
        URLQueryItem(name: "count", value: "10")
    ]

    var request = URLRequest(url: components.url!)
    request.httpMethod = "GET"
    request.setValue("<your-api-key>", forHTTPHeaderField: "Authorization")
    request.setValue("application/json", forHTTPHeaderField: "Content-Type")

    let task = URLSession.shared.dataTask(with: request) { data, response, error in
        if let error = error {
            print("Error: \(error)")
            return
        }
        if let data = data, let responseString = String(data: data, encoding: .utf8) {
            print("Response: \(responseString)")
        }
    }

    task.resume()

Parameters

Required

url: The endpoint for the Basic X Search API.
params/body: A JSON string or dictionary containing:
- query: Search query. For syntax, check https://github.com/igorbrigadir/twitter-advanced-search, e.g., "Bittensor".

Optional

sort: Sort by Top or Latest, e.g., "Top".
count: Number of tweets to retrieve, e.g., 20.

Response Sample

Based on the above code, here is how the response is retrieved as JSON. Each coding language has its own way of retrieving data from the below JSON.

json

    [
        {
            "user": {
            "id": "1453417787746029577",
            "url": "https://x.com/firsttensor",
            "name": "Firsττensor - Biττensor Validator",
            "username": "firsttensor",
            "created_at": "2021-10-27",
            "followers_count": 4669,
            "profile_image_url": "https://pbs.twimg.com/profile_images/1890150870563614720/L3PGGoUs_normal.jpg"
            },
            "id": "1891203972003684353",
            "text": "How to Stake/Unstake $TAO to the FirstTensor Validator Using the YUMA Platform.\n\n✅ Make sure your wallet is imported into the Polkadot.js or Bittensor Wallet extension.\n\n👇Share this so everyone can use it! \n\n#bittensor #delegate #root",
            "retweet_count": 2,
            "like_count": 7,
            "created_at": "2025-02-16",
            "url": "https://x.com/firsttensor/status/1891203972003684353",
            "media": [
            {
                "media_url": "https://pbs.twimg.com/ext_tw_video_thumb/1891202584314105856/pu/img/nzOtIMS_Zz7YWHJY.jpg",
                "type": "video"
            }
            ],
            "hashtags": ["bittensor", "delegate", "root"]
        }
    ]

Test API

To experiment with the Basic X Search API and see it in action, visit the Basic X Search API.

X Search Operators Guide

X search operators allow users to refine their searches on Web, Mobile, and TweetDeck.

Search Operators

Here are the primary operations that can be used over tweets, users, engagement, media, and more.

Tweet Content

keyword1 keyword2 - Tweets containing both words (AND logic).
keyword1 OR keyword2 – Tweets containing either word. "exact phrase" – Matches the complete phrase. +word – Forces inclusion of the word. -word – Excludes the word. #hashtag – Searches for tweets with a specific hashtag. $TWTR – Searches for stock symbols (cashtags). url:example.com – Finds tweets linking to a specific domain. lang:en – Filters tweets by language.

User-Based Filters

from:user – Tweets from a specific user.
to:user – Replies to a specific user. @user – Mentions of a specific user. filter:verified – Tweets from verified users.

Geolocation Filters

near:city – Tweets geotagged to a location.
within:10km – Restricts results to a radius from the specified location. geocode:lat,long,radius – Searches within a specific latitude and longitude.

Date & Time Filters

since:YYYY-MM-DD – Tweets from a specified date onward.
until:YYYY-MM-DD – Tweets before a specified date. since_time:timestamp – Tweets after a UNIX timestamp. until_time:timestamp – Tweets before a UNIX timestamp.

Tweet Type Filters

filter:retweets – Shows retweets.
filter:replies – Shows only replies. filter:quote – Shows quote tweets. conversation_id:tweet_id – Finds tweets within a specific thread.

Engagement Filters

min_retweets:10 – Tweets with at least 10 retweets.
min_faves:50 – Tweets with at least 50 likes. min_replies:5 – Tweets with at least 5 replies. min_retweets:100 – Tweets with a maximum of 100 retweets.

Media Filters

filter:media – Tweets with any media.
filter:images – Tweets with images. filter:videos – Tweets with videos. filter:native_video – Tweets with X hosted videos. filter:spaces – Tweets from X Spaces.

Additional Filters

filter:links – Tweets containing links.
filter:mentions – Tweets with mentions. filter:news – Tweets linking to news articles. filter:safe – Excludes NSFW content.

App-Specific Filters

source:client_name – Tweets from a specific app (e.g., TweetDeck).
card_name:summary_large_image – Tweets containing large summary cards. card_name:player – Tweets with embedded players.

Matching Behavior

By default, X displays “Top” results, prioritizing tweets with engagement. Keyword searches match tweet text, usernames, screen names, and URLs.

📘 Advance X Search

For more details on using advance X search operators, please visit here.