# Retrieve search results by keyword {% hint style="danger" %} **WARNING:** **You are viewing an outdated version of our documentation.** \ **For the latest and most accurate information, please visit** [**docs.socialdata.tools**](https://docs.socialdata.tools)**.** {% endhint %} Returns array of tweets provided by Twitter search page. Typically Twitter returns \~20 results per page. You can request additional search results by sending another request to the same endpoint using cursor parameter. ### Endpoint ```url GET https://api.socialdata.tools/twitter/search ``` ### Endpoint parameters | Name | Description | Example | | ------------------------------------------- | ------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------- | |

query
(Required)

| A UTF-8, URL-encoded search query, including any operators supported by Twitter website search | from:elonmusk doge | |

cursor
(Optional)

| Cursor value obtained from next\_cursor response property | DAACCgACGC12FhmAJxAKAAMYLXYWGX\_Y8AgABAAAAAILAAUAAADoRW1QQzZ3QUFBZlEvZ0d... | |

type
(Optional)

|

Search type (Latest for recent tweets or Top for popular tweets)

Default: Latest

| Top | ### Using search operators This endpoint supports all search operators supported by Twitter. Search operators must be included as part of `query` parameter and not as separate endpoint parameters. Some frequently used search operators: * `from:USERNAME` will return all tweets and replies made by user * `from:USERNAME filter:replies` will return only replies, but not tweets * `from:USERNAME -filter:replies` will return only tweets, but not replies * `since_time:TIMESTAMP` and `until_time:TIMESTAMP` will return tweets and comments posted after or before the provided UNIX timestamp * `since_id:TWEET_ID` and `max_id:TWEET_ID` will return tweets with ID higher or lower than the provided TWEET\_ID * `conversation_id:TWEET_ID` will return all comments posted in response to TWEET\_ID For a more detailed overview of Twitter search operators refer to the following page: ### Known Limitations Twitter removes tweets flagged as spam, or all tweets from all shadow-banned users. Request to retrieve tweets or comments made by a shadow-banned user (i.e. `from:USERNAME`) will always return 0 tweets, but the user's timeline is still available through [User tweets and replies](/docs/twitter-users/retrieve-tweets-and-replies-made-by-a-specific-user.md) endpoint. ### Retrieving large datasets While Twitter returns a limited number of results when using "Latest" search filter, it is possible to cycle through a larger dataset using `max_id:` and `since_id:` search operators. When retrieving Latest search results, Twitter provides the response with tweets sorted by ID in descending order. If you need to retrieve more posts - simply make another request with the same query adding `max_id:[lowest ID from current dataset].`Using this approach it is possible to extract the entire timeline from the moment an account was registered. ### Response codes * **HTTP 200 OK -** succeeded * **HTTP 402 Payment Required** - not enough credits to perform this request * **HTTP 404 Not Found** - requested tweet does not exist * **HTTP 422 Unprocessable Content** - validation failed (e.g. one of the required parameters was not provided) * **HTTP 500** **Internal Server Error** - other error, typically means that SocialData API failed to obtain the requested information and you should try again later ### Rate limits By default each user has a limit of 120 requests per minute shared across all endpoints. Please reach out to if you need to raise your rate limit. ### Example request ```bash curl "https://api.socialdata.tools/twitter/search?query=from%3Aelonmusk&type=Latest" -H 'Authorization: Bearer API_KEY' -H 'Accept: application/json' ``` [![Run In Postman](https://run.pstmn.io/button.svg)](https://god.gw.postman.com/run-collection/36444222-9d3f261a-6fc3-44cd-90eb-f0d191d6d1a8?action=collection%2Ffork\&source=rip_markdown\&collection-url=entityId%3D36444222-9d3f261a-6fc3-44cd-90eb-f0d191d6d1a8%26entityType%3Dcollection%26workspaceId%3D22407140-425b-41ff-969e-1fb938fe8e86) ### Example response ```json // If succeeded: { "next_cursor": "DAACCgACGC12FhmAJxAKAAMYLXYWGX_Y8AgABAAAAAILAAUAAADoRW1QQzZ3QUFBZlEvZ0dKTjB2R3AvQUFBQUJNWUxTNkQyQmFoUXhndFRReS9Ga0NOR0MwZG9yS1hzU2NZTFFwYm0xY1I0aGd0YmhZc1drQ3FHQzBjUXNSV1lSZ1lMVml5V3BxQU9CZ3RMbUhUV2tDb0dDMVFuVW1YMEFzWUxKYURhOVpob3hndFZtaklGakNNR0MxWGdlT1dZSE1ZTFRYNFNwZUEraGd0Y2h2bEYxRkxHQzFNMi83V1VGc1lMTTZwemhZQWt4Z3RWMkJKbDNGN0dDMWFGTXBYUUY4WUxUUERuRlp3UVE9PQgABgAAAAAIAAcAAAAADAAICgABGCyWg2vWYaMAAAA", "tweets": [ { "tweet_created_at": "2023-12-13T05:39:09.000000Z", "id_str": "1734810168053956719", "text": null, "full_text": "@TeslaHype Pace of Progress", "source": "Twitter for iPhone<\\/a>", "truncated": false, "in_reply_to_status_id_str": "1734777084268920960", "in_reply_to_user_id_str": "1311506622821400581", "in_reply_to_screen_name": "TeslaHype", "user": { "id_str": "44196397", "name": "Elon Musk", "screen_name": "elonmusk", "location": "\\ud835\\udd4f\\u00d0", "url": null, "description": "", "protected": false, "verified": false, "followers_count": 166213349, "friends_count": 506, "listed_count": 149586, "favourites_count": 37958, "statuses_count": 34934, "created_at": "2009-06-02T20:12:29.000000Z", "profile_banner_url": "https:\\/\\/pbs.twimg.com\\/profile_banners\\/44196397\\/1690621312", "profile_image_url_https": "https:\\/\\/pbs.twimg.com\\/profile_images\\/1683325380441128960\\/yRsRRjGO_normal.jpg", "can_dm": false }, "quoted_status_id_str": null, "is_quote_status": false, "quoted_status": null, "retweeted_status": null, "quote_count": 11, "reply_count": 156, "retweet_count": 78, "favorite_count": 977, "lang": "en", "entities": { "user_mentions": [ { "id_str": "1311506622821400581", "name": "Tesla Hype", "screen_name": "TeslaHype", "indices": [ 0, 10 ] } ], "urls": [], "hashtags": [], "symbols": [] }, "views_count": 32377, "bookmark_count": 19 }, { "tweet_created_at": "2023-12-13T05:38:26.000000Z", "id_str": "1734809984674693446", "text": null, "full_text": "@anammostarac Yeah", "source": "Twitter for iPhone<\\/a>", "truncated": false, "in_reply_to_status_id_str": "1734809562258276654", "in_reply_to_user_id_str": "2852570664", "in_reply_to_screen_name": "anammostarac", "user": { "id_str": "44196397", "name": "Elon Musk", "screen_name": "elonmusk", "location": "\\ud835\\udd4f\\u00d0", "url": null, "description": "", "protected": false, "verified": false, "followers_count": 166213349, "friends_count": 506, "listed_count": 149586, "favourites_count": 37958, "statuses_count": 34934, "created_at": "2009-06-02T20:12:29.000000Z", "profile_banner_url": "https:\\/\\/pbs.twimg.com\\/profile_banners\\/44196397\\/1690621312", "profile_image_url_https": "https:\\/\\/pbs.twimg.com\\/profile_images\\/1683325380441128960\\/yRsRRjGO_normal.jpg", "can_dm": false }, "quoted_status_id_str": null, "is_quote_status": false, "quoted_status": null, "retweeted_status": null, "quote_count": 4, "reply_count": 64, "retweet_count": 30, "favorite_count": 513, "lang": "en", "entities": { "user_mentions": [ { "id_str": "2852570664", "name": "Ana Mostarac", "screen_name": "anammostarac", "indices": [ 0, 13 ] } ], "urls": [], "hashtags": [], "symbols": [] }, "views_count": 25579, "bookmark_count": 3 } ] ] // If failed: { "status":"error", "message":"Failed to fetch data from Twitter" } ``` --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://socialdata.gitbook.io/docs/twitter-tweets/retrieve-search-results-by-keyword.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.