> ## Documentation Index > Fetch the complete documentation index at: https://developers.gopher-ai.com/llms.txt > Use this file to discover all available pages before exploring further. # Twitter All job types use the `/api/v1/search/live` POST endpoint and follow the same structure: a top-level `type` to define the data source, and a set of `arguments` defining the parameters of the job. Search tweets using Twitter query syntax Get user profile information and timelines Get replies, retweets, and specific tweets by ID Get followers, following, and trending topics Extract media from tweets and profiles Discover trending topics and hashtags ## Overview The Twitter API provides comprehensive access to Twitter data including tweets, user profiles, social networks, and trending content. It supports multiple authentication methods and offers extensive search and interaction capabilities. ### `twitter` The primary job type for Twitter data extraction, automatically using the best available authentication method. **Use Cases:** * Social media monitoring and analysis * Content discovery and research * User engagement analysis * Trend monitoring and hashtag tracking * Media content extraction * Social network analysis ## Parameters ### Common Parameters | Parameter | Type | Required | Default | Description | | ------------- | ------- | -------- | ------- | ---------------------------------------------------------- | | `type` | string | Yes | - | The operation type (see capabilities below) | | `query` | string | No | - | The query to execute (username, tweet ID, or search terms) | | `max_results` | integer | No | `1000` | Maximum number of results to return (max 1000) | | `count` | integer | No | - | Number of results per request (max 1000) | | `next_cursor` | string | No | - | Pagination cursor for retrieving subsequent pages | | `start_time` | string | No | - | ISO timestamp to filter results created after this time | | `end_time` | string | No | - | ISO timestamp to filter results created before this time | ### Query Types * **Search Queries**: Use Twitter search syntax for finding tweets * **Usernames**: Use @username format for user-specific operations * **Tweet IDs**: Use numeric IDs for specific tweet operations * **User IDs**: Use numeric IDs for user profile operations ## Capabilities ### Tweet Operations | Capability | Description | Query Type | Max Results | | --------------------- | ------------------------------------------------ | ------------ | ----------- | | `searchbyquery` | Search tweets using Twitter query syntax | Search terms | 1000 | | `searchbyfullarchive` | Search historical tweets (requires elevated API) | Search terms | 1000 | | `getbyid` | Get specific tweet by ID | Tweet ID | 1 | | `getreplies` | Get replies to a specific tweet | Tweet ID | 1000 | | `getretweeters` | Get users who retweeted a tweet | Tweet ID | 1000 | | `getmedia` | Get media from tweets | Username/ID | 1000 | | `gettweets` | Get tweets from user timeline | Username/ID | 1000 | ### Profile Operations | Capability | Description | Query Type | Max Results | | ----------------- | ------------------------------------- | ----------- | ----------- | | `searchbyprofile` | Get user profile information | Username | 1 | | `getprofilebyid` | Get user profile by user ID | User ID | 1 | | `getfollowers` | Get followers of a profile | Username/ID | 1000 | | `getfollowing` | Get users that a profile is following | Username/ID | 1000 | ### Special Operations | Capability | Description | Query Type | Max Results | | ----------- | ------------------------------ | ---------- | ----------- | | `gettrends` | Get trending topics | None | Varies | | `getspace` | Get Twitter Spaces information | Space ID | 1 | ## Examples ### Tweet Search Operations #### Basic Tweet Search ```json theme={null} { "type": "twitter", "arguments": { "type": "searchbyquery", "query": "gopher_ai", "max_results": 10 } } ``` #### Advanced Tweet Search with Time Filters ```json theme={null} { "type": "twitter", "arguments": { "type": "searchbyquery", "query": "artificial intelligence", "max_results": 100, "start_time": "2024-01-01T00:00:00Z", "end_time": "2024-01-31T23:59:59Z" } } ``` #### Historical Tweet Search (Elevated API) ```json theme={null} { "type": "twitter", "arguments": { "type": "searchbyfullarchive", "query": "machine learning", "max_results": 50, "start_time": "2023-01-01T00:00:00Z" } } ``` #### Get Specific Tweet ```json theme={null} { "type": "twitter", "arguments": { "type": "getbyid", "query": "1881258110712492142" } } ``` #### Get Tweet Replies ```json theme={null} { "type": "twitter", "arguments": { "type": "getreplies", "query": "1234567890", "max_results": 20 } } ``` #### Get Tweet Retweeters ```json theme={null} { "type": "twitter", "arguments": { "type": "getretweeters", "query": "1234567890", "max_results": 50 } } ``` #### Get User Timeline ```json theme={null} { "type": "twitter", "arguments": { "type": "gettweets", "query": "gopher_ai", "max_results": 50 } } ``` #### Get Media from Tweets ```json theme={null} { "type": "twitter", "arguments": { "type": "getmedia", "query": "gopher_ai", "max_results": 25 } } ``` ### Profile Operations #### Get User Profile by Username ```json theme={null} { "type": "twitter", "arguments": { "type": "searchbyprofile", "query": "gopher_ai" } } ``` #### Get User Profile by ID ```json theme={null} { "type": "twitter", "arguments": { "type": "getprofilebyid", "query": "44196397" } } ``` #### Get User Followers ```json theme={null} { "type": "twitter", "arguments": { "type": "getfollowers", "query": "gopher_ai", "max_results": 200 } } ``` #### Get User Following ```json theme={null} { "type": "twitter", "arguments": { "type": "getfollowing", "query": "gopher_ai", "max_results": 200 } } ``` ### Special Operations #### Get Trending Topics ```json theme={null} { "type": "twitter", "arguments": { "type": "gettrends" } } ``` #### Get Twitter Space ```json theme={null} { "type": "twitter", "arguments": { "type": "getspace", "query": "1YqKDqWqdPLsV" } } ``` ## Use Case Examples ### Social Media Monitoring Monitor mentions and hashtags: ```json theme={null} { "type": "twitter", "arguments": { "type": "searchbyquery", "query": "#AI OR #MachineLearning OR #ArtificialIntelligence", "max_results": 100, "start_time": "2024-01-01T00:00:00Z" } } ``` ### Competitor Analysis Analyze competitor mentions: ```json theme={null} { "type": "twitter", "arguments": { "type": "searchbyquery", "query": "@competitor OR competitor_name", "max_results": 50 } } ``` ### Influencer Research Research user engagement: ```json theme={null} { "type": "twitter", "arguments": { "type": "getfollowers", "query": "influencer_username", "max_results": 1000 } } ``` ### Content Discovery Find viral content: ```json theme={null} { "type": "twitter", "arguments": { "type": "searchbyquery", "query": "viral OR trending", "max_results": 200 } } ``` ## Best Practices ### 1. Query Optimization * Use specific keywords and hashtags for targeted results * Combine multiple terms with OR/AND operators * Use quotes for exact phrase matching * Include relevant filters (lang:, from:, etc.) ### 2. Rate Limiting * Be mindful of API rate limits * Use appropriate `max_results` values * Implement pagination with `next_cursor` * Cache results when possible ### 3. Time Filtering * Use `start_time` and `end_time` for historical data * Consider timezone implications * Use ISO 8601 format for timestamps ### 4. Result Management * Set appropriate `max_results` based on your needs * Use pagination for large result sets * Consider the cost of high-volume requests ## Response Data The Twitter API returns structured data including: ### Tweet Data * **Content**: Tweet text, media, links * **Metadata**: Timestamps, engagement metrics * **User Info**: Author details and verification status * **Interactions**: Reply, retweet, like counts ### Profile Data * **Basic Info**: Username, display name, bio * **Metrics**: Follower count, following count, tweet count * **Verification**: Account verification status * **Media**: Profile and banner images ### Social Network Data * **Followers**: User profiles of followers * **Following**: User profiles being followed * **Engagement**: Interaction patterns and metrics ## Limitations * Maximum 1000 results per request (`max_results` limit) * Historical search requires elevated API access * Some data may be limited by privacy settings * Rate limiting applies to prevent excessive API usage * Real-time data availability may vary ## Error Handling ### Common Error Scenarios #### Invalid Query Format Ensure queries follow Twitter search syntax: * Use proper operators (OR, AND, NOT) * Quote phrases that need exact matching * Use valid hashtag and mention formats #### Exceeding Limits * `max_results` cannot exceed 1000 * `count` cannot exceed 1000 * Large requests may be rate limited #### Missing Required Parameters * `type` is required for all operations * `query` is required for most operations (except `gettrends`) #### Authentication Issues * Some capabilities require specific authentication methods * Elevated API access needed for historical search * Rate limits vary by authentication type ## Notes * All timestamps use ISO 8601 format * Pagination is supported via `next_cursor` parameter * Search results are returned in reverse chronological order * Media URLs may have expiration times * Some capabilities may require specific API access levels