Docs

Search

Powerful search capabilities for tweets, users, and hashtags with advanced filtering.

Overview

The Search endpoint provides comprehensive search capabilities for tweets with advanced filter options, date range restrictions, and language detection.

Endpoints

Search Tweets

Searches for tweets based on keywords and filters.

GET /search/tweets

Parameters

Name	Type	Required	Description
`q`	string	Yes	Search term (keywords, hashtags, etc.)
`limit`	integer	No	Number of results (Default: 20, Max: 100)
`cursor`	string	No	Cursor for pagination
`lang`	string	No	Language (ISO 639-1 code, e.g. "en", "de")
`since`	string	No	Start date (ISO 8601: YYYY-MM-DD)
`until`	string	No	End date (ISO 8601: YYYY-MM-DD)
`from`	string	No	Only tweets from this username
`to`	string	No	Only tweets to this username
`filter`	string	No	Filter: `top`, `latest`, `media`, `videos`
`verified_only`	boolean	No	Only verified accounts (Default: false)
`min_replies`	integer	No	Minimum number of replies
`min_likes`	integer	No	Minimum number of likes
`min_retweets`	integer	No	Minimum number of retweets

Headers

X-API-KEY: <YOUR_API_KEY>

Response Example

{
  "data": [
    {
      "id": "1234567890123456789",
      "text": "This is a tweet about #API development",
      "author": {
        "id": "987654321",
        "username": "developer",
        "name": "Dev User",
        "verified": true
      },
      "created_at": "2024-10-01T12:00:00.000Z",
      "lang": "en",
      "metrics": {
        "retweet_count": 42,
        "reply_count": 15,
        "like_count": 256,
        "quote_count": 8
      },
      "entities": {
        "hashtags": ["API"],
        "urls": [],
        "mentions": []
      }
    }
  ],
  "meta": {
    "result_count": 20,
    "next_cursor": "eyJpZCI6IjEyMzQ1Njc4OTAxMjM0NTY3ODkifQ=="
  }
}

Advanced Search

Advanced search with complex filter options.

POST /search/advanced

Request Body

{
  "query": {
    "keywords": ["AI", "machine learning"],
    "hashtags": ["tech", "innovation"],
    "mention": "@example_user",
    "exclude_keywords": ["spam"],
    "exclude_hashtags": ["ad"]
  },
  "filters": {
    "date_range": {
      "from": "2024-09-01",
      "to": "2024-10-01"
    },
    "engagement": {
      "min_likes": 100,
      "min_retweets": 50
    },
    "author": {
      "verified_only": true,
      "min_followers": 1000
    },
    "content_type": {
      "has_media": true,
      "has_video": false,
      "has_links": false
    },
    "language": "en"
  },
  "sort": "engagement",
  "limit": 50
}

Response Example

{
  "data": [
    {
      "id": "1234567890123456789",
      "text": "Advanced search result about AI and machine learning #tech #innovation",
      "author": {...},
      "created_at": "2024-09-15T14:30:00.000Z",
      "metrics": {
        "like_count": 523,
        "retweet_count": 187
      },
      "media": [...]
    }
  ],
  "meta": {
    "result_count": 50,
    "total_results": 1523,
    "query_time_ms": 245
  }
}

Search by Hashtag

Searches for tweets with a specific hashtag.

GET /search/hashtag/{hashtag}

Parameters

Name	Type	Required	Description
`hashtag`	string	Yes	The hashtag (without #)
`limit`	integer	No	Number of results (Default: 20, Max: 100)
`filter`	string	No	`top` or `latest` (Default: latest)

Response Example

{
  "hashtag": "API",
  "data": [
    {
      "id": "1234567890123456789",
      "text": "Tweet with #API hashtag",
      "author": {...},
      "created_at": "2024-10-01T12:00:00.000Z"
    }
  ],
  "meta": {
    "result_count": 20,
    "hashtag_stats": {
      "total_tweets_24h": 15420,
      "trending_score": 8.7
    }
  }
}

Search by Location

Searches for tweets from a specific location.

GET /search/location

Parameters

Name	Type	Required	Description
`q`	string	Yes	Search term
`latitude`	float	Yes	Latitude
`longitude`	float	Yes	Longitude
`radius`	string	No	Radius (e.g. "10km", "5mi") Default: 10km
`limit`	integer	No	Number of results (Default: 20, Max: 100)

Response Example

{
  "data": [
    {
      "id": "1234567890123456789",
      "text": "Tweet from this location",
      "author": {...},
      "geo": {
        "place_id": "abc123",
        "full_name": "San Francisco, CA",
        "coordinates": {
          "lat": 37.7749,
          "lon": -122.4194
        }
      }
    }
  ],
  "meta": {
    "result_count": 15,
    "search_location": {
      "lat": 37.7749,
      "lon": -122.4194,
      "radius": "10km"
    }
  }
}

Search Query Operators

You can use these operators in the q parameter:

Operator	Example	Description
`"exact phrase"`	`"machine learning"`	Exact phrase
`OR`	`AI OR ML`	One of the keywords
`AND`	`AI AND ML`	Both keywords
`-`	`AI -spam`	Exclude keyword
`#`	`#tech`	Hashtag
`@`	`@username`	Mention
`from:`	`from:elonmusk`	From user
`to:`	`to:support`	To user
`since:`	`since:2024-01-01`	Since date
`until:`	`until:2024-12-31`	Until date
`filter:verified`	-	Only verified
`filter:media`	-	Only with media
`filter:videos`	-	Only with videos
`filter:images`	-	Only with images
`filter:links`	-	Only with links

Example Queries

"artificial intelligence" #tech filter:verified min_likes:100
AI OR ML -spam from:openai since:2024-01-01
#bitcoin filter:media min_retweets:50

Rate Limits

Basic Plan: 50 Requests/hour
Pro Plan: 500 Requests/hour
Enterprise Plan: 5,000 Requests/hour

Error Codes

Code	Description
400	Bad Request - Invalid parameters or query
401	Unauthorized - Missing or invalid API Key
422	Unprocessable Entity - Query too complex
429	Too Many Requests - Rate limit exceeded
500	Internal Server Error

Users Trends