Twitter - Gopher

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.

Tweet Search

Search tweets using Twitter query syntax

User Profiles

Get user profile information and timelines

Tweet Interactions

Get replies, retweets, and specific tweets by ID

Social Networks

Get followers, following, and trending topics

Media Content

Extract media from tweets and profiles

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

{
  "type": "twitter",
  "arguments": {
    "type": "searchbyquery",
    "query": "gopher_ai",
    "max_results": 10
  }
}

Advanced Tweet Search with Time Filters

{
  "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)

{
  "type": "twitter",
  "arguments": {
    "type": "searchbyfullarchive",
    "query": "machine learning",
    "max_results": 50,
    "start_time": "2023-01-01T00:00:00Z"
  }
}

Get Specific Tweet

{
  "type": "twitter",
  "arguments": {
    "type": "getbyid",
    "query": "1881258110712492142"
  }
}

Get Tweet Replies

{
  "type": "twitter",
  "arguments": {
    "type": "getreplies",
    "query": "1234567890",
    "max_results": 20
  }
}

Get Tweet Retweeters

{
  "type": "twitter",
  "arguments": {
    "type": "getretweeters",
    "query": "1234567890",
    "max_results": 50
  }
}

Get User Timeline

{
  "type": "twitter",
  "arguments": {
    "type": "gettweets",
    "query": "gopher_ai",
    "max_results": 50
  }
}

Get Media from Tweets

{
  "type": "twitter",
  "arguments": {
    "type": "getmedia",
    "query": "gopher_ai",
    "max_results": 25
  }
}

Profile Operations

Get User Profile by Username

{
  "type": "twitter",
  "arguments": {
    "type": "searchbyprofile",
    "query": "gopher_ai"
  }
}

Get User Profile by ID

{
  "type": "twitter",
  "arguments": {
    "type": "getprofilebyid",
    "query": "44196397"
  }
}

Get User Followers

{
  "type": "twitter",
  "arguments": {
    "type": "getfollowers",
    "query": "gopher_ai",
    "max_results": 200
  }
}

Get User Following

{
  "type": "twitter",
  "arguments": {
    "type": "getfollowing",
    "query": "gopher_ai",
    "max_results": 200
  }
}

Special Operations

{
  "type": "twitter",
  "arguments": {
    "type": "gettrends"
  }
}

Get Twitter Space

{
  "type": "twitter",
  "arguments": {
    "type": "getspace",
    "query": "1YqKDqWqdPLsV"
  }
}

Use Case Examples

Monitor mentions and hashtags:

{
  "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:

{
  "type": "twitter",
  "arguments": {
    "type": "searchbyquery",
    "query": "@competitor OR competitor_name",
    "max_results": 50
  }
}

Influencer Research

Research user engagement:

{
  "type": "twitter",
  "arguments": {
    "type": "getfollowers",
    "query": "influencer_username",
    "max_results": 1000
  }
}

Content Discovery

Find viral content:

{
  "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

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

Tweet Search

User Profiles

Tweet Interactions

Social Networks

Media Content

Trending Topics

​Overview

​twitter

​Parameters

​Common Parameters

​Query Types

​Capabilities

​Tweet Operations

​Profile Operations

​Special Operations

​Examples

​Tweet Search Operations

​Basic Tweet Search

​Advanced Tweet Search with Time Filters

​Historical Tweet Search (Elevated API)

​Get Specific Tweet

​Get Tweet Replies

​Get Tweet Retweeters

​Get User Timeline

​Get Media from Tweets

​Profile Operations

​Get User Profile by Username

​Get User Profile by ID

​Get User Followers

​Get User Following

​Special Operations

​Get Trending Topics

​Get Twitter Space

​Use Case Examples

​Social Media Monitoring

​Competitor Analysis

​Influencer Research

​Content Discovery

​Best Practices

​1. Query Optimization

​2. Rate Limiting

​3. Time Filtering

​4. Result Management

​Response Data

​Tweet Data

​Profile Data

​Social Network Data

​Limitations

​Error Handling

​Common Error Scenarios

​Invalid Query Format

​Exceeding Limits

​Missing Required Parameters

​Authentication Issues

​Notes

Overview

`twitter`

Parameters

Common Parameters

Query Types

Capabilities

Tweet Operations

Profile Operations

Special Operations

Examples

Tweet Search Operations

Basic Tweet Search

Advanced Tweet Search with Time Filters

Historical Tweet Search (Elevated API)

Get Specific Tweet

Get Tweet Replies

Get Tweet Retweeters

Get User Timeline

Get Media from Tweets

Profile Operations

Get User Profile by Username

Get User Profile by ID

Get User Followers

Get User Following

Special Operations

Get Trending Topics

Get Twitter Space

Use Case Examples

Social Media Monitoring

Competitor Analysis

Influencer Research

Content Discovery

Best Practices

1. Query Optimization

2. Rate Limiting

3. Time Filtering

4. Result Management

Response Data

Tweet Data

Profile Data

Social Network Data

Limitations

Error Handling

Common Error Scenarios

Invalid Query Format

Exceeding Limits

Missing Required Parameters

Authentication Issues

Notes