Skip to main content

​
X Queries Introduction

X Queries provide direct access to Twitter/X data and user information through REST API endpoints, enabling you to retrieve specific tweets, user profiles, and engagement metrics on demand.

​
What are X Queries?

X Queries allow you to make direct API calls to retrieve Twitter/X data without setting up ongoing tracking or webhooks. Perfect for one-time data retrieval, search queries, and user information lookups.

​
Key Features

​
On-Demand Access

  • Immediate Results: Get data instantly without setup
  • No Configuration: No need to create tracking configurations
  • Flexible Queries: Query specific tweets, users, or content
  • Pay-per-Use: Only pay for the data you retrieve

​
Comprehensive Data

  • Full Tweet Content: Complete tweet text, media, and metadata
  • User Profiles: Detailed user information and statistics
  • Engagement Metrics: Likes, retweets, replies, and quotes
  • Historical Access: Access historical tweet data when available
  • Keyword Search: Search for specific terms and phrases
  • User Search: Find users by username or criteria
  • Hashtag Search: Search hashtag usage and trends
  • Geographic Search: Search content from specific locations

​
Available Query Types

​
Tweet Queries

  • Get Tweet: Retrieve specific tweet by ID
  • Search Tweets: Search tweets by keywords, hashtags, or criteria
  • User Timeline: Get tweets from specific user timelines
  • Trending Topics: Get current trending topics and hashtags

​
User Queries

  • Get User: Retrieve user profile information by username or ID
  • User Lookup: Find users by email or other criteria
  • User Timeline: Get user’s recent tweets and activity
  • Followers/Following: Get user’s follower and following lists

​
Analytics Queries

  • Tweet Metrics: Get detailed engagement metrics for tweets
  • User Analytics: Get user statistics and growth data
  • Trend Analysis: Analyze trending topics and hashtags
  • Sentiment Analysis: Get sentiment data for tweets or topics

​
Use Cases

​
Content Discovery

  • Research: Find specific tweets or content for research purposes
  • Journalism: Locate relevant tweets and user statements
  • Content Curation: Discover trending content and viral posts
  • Fact Checking: Verify claims and find original sources

​
User Analysis

  • Profile Research: Get detailed user information and statistics
  • Influencer Identification: Find influential users in specific niches
  • Competitor Analysis: Analyze competitor profiles and activity
  • User Verification: Verify user identities and profiles

​
Data Collection

  • One-Time Queries: Retrieve specific data without ongoing tracking
  • Bulk Data: Collect large datasets for analysis
  • Historical Research: Access historical tweet data
  • API Integration: Integrate Twitter/X data into your applications

​
Query Parameters

​
Common Parameters

  • query: Search query or keywords
  • max_results: Maximum number of results to return
  • sort: Sort order (relevance, recent, popular)
  • lang: Language filter
  • exclude: Content to exclude (retweets, replies)

​
Advanced Parameters

  • since: Start date for time-based filtering
  • until: End date for time-based filtering
  • geo: Geographic location filter
  • verified: Filter for verified users only
  • min_likes: Minimum like count filter
  • min_retweets: Minimum retweet count filter

​
Response Format

​
Standard Response Structure

{
  "data": {
    "id": "1234567890123456789",
    "text": "This is a tweet...",
    "created_at": "2024-01-15T10:30:00Z",
    "author": {
      "id": "987654321",
      "username": "example_user",
      "name": "Example User",
      "verified": true,
      "followers_count": 15000
    },
    "public_metrics": {
      "retweet_count": 25,
      "like_count": 150,
      "reply_count": 12,
      "quote_count": 5
    }
  },
  "meta": {
    "result_count": 1,
    "total_results": 150,
    "next_token": "next_page_token"
  }
}

​
Rate Limits

​
Query Limits

  • Standard Queries: 300 requests per 15 minutes per API key
  • Search Queries: 300 requests per 15 minutes per API key
  • User Queries: 300 requests per 15 minutes per API key
  • Premium Queries: Higher limits available for premium plans

​
Data Limits

  • Max Results: 100 results per query for standard endpoints
  • Historical Access: Full historical access for premium plans
  • Data Retention: 7 days for standard, 30 days for premium
  • Rate Limit Headers: Rate limit information in response headers

​
Authentication

​
API Key Authentication

All X Query endpoints require API key authentication: 
Authorization: Bearer YOUR_API_KEY

​
Permissions Required

  • Read Access: Basic read access to Twitter/X data
  • User Data: Access to user profile information
  • Tweet Data: Access to tweet content and metrics
  • Search Access: Access to search and discovery features

​
Error Handling

​
Common Error Codes

  • 400 Bad Request: Invalid query parameters or syntax
  • 401 Unauthorized: Invalid or missing API key
  • 403 Forbidden: Insufficient permissions for requested data
  • 404 Not Found: Requested tweet or user not found
  • 429 Too Many Requests: Rate limit exceeded
  • 500 Internal Server Error: Temporary server error

​
Error Response Format

{
  "error": "Tweet not found",
  "code": 404,
  "details": {
    "tweet_id": "1234567890123456789"
  },
  "timestamp": "2024-01-15T10:30:00Z",
  "requestId": "req_1234567890"
}

​
Getting Started

​
1. Get Your API Key

  1. Sign up at Scrapest Dashboard
  2. Navigate to API Keys section
  3. Generate a new API key with X Query permissions
  4. Copy and securely store your API key

​
2. Make Your First Query

curl -X GET "https://api.scrape.st/x/user/username" \
  -H "Authorization: Bearer YOUR_API_KEY"

​
3. Explore Endpoints

​
Best Practices

​
For Efficient Queries

  • Specific Queries: Use specific parameters to reduce data volume
  • Pagination: Use pagination for large result sets
  • Caching: Cache frequently accessed data
  • Batch Requests: Combine multiple queries when possible

​
For Error Handling

  • Rate Limiting: Implement rate limiting and backoff logic
  • Retry Logic: Handle temporary failures with retries
  • Validation: Validate query parameters before sending
  • Logging: Log all queries and responses for debugging

​
For Data Management

  • Data Validation: Validate received data before processing
  • Storage Planning: Plan appropriate storage for query results
  • Privacy Compliance: Ensure compliance with data privacy regulations
  • Cost Management: Monitor query volume and costs

​
SDKs and Tools

​
Official SDKs

  • JavaScript/Node.js: npm install @scrapest/x-queries
  • Python: pip install scrapest-x-queries
  • cURL: Native command-line support

​
Third-Party Tools

  • Postman Collections: Pre-configured API request collections
  • Swagger UI: Interactive API documentation
  • Monitoring Tools: Query performance and usage monitoring

​
Support and Resources

​
Documentation

  • API Reference: Detailed endpoint documentation and examples
  • Query Builder: Interactive query building tool
  • Best Practices: Recommended patterns and guidelines
  • Troubleshooting: Common issues and solutions

​
Community

  • GitHub: Open-source issues and discussions
  • Discord: Real-time community support
  • Stack Overflow: Technical questions and answers
  • Blog: Product updates and technical articles
Next: User Information