A Val Town application that uses xAI's Grok API to search and retrieve information from X (Twitter) users.

• 🌐 Web Interface: User-friendly HTML frontend
• 🔍 Natural Language Search: Query X posts using conversational language
• 👥 Target Users: Focus on specific users or general searches
• 📅 Date Filtering: Search within specific time ranges
• 🖼️ Media Analysis: Include image and video analysis
• 🔗 Citations: Get source links for all results
• 🚀 Fast API: Direct JSON API for programmatic access

Simply visit your val's URL in a web browser:

https://your-val-url.web.val.run

The web interface provides:

• Intuitive form with all search options
• Real-time loading states
• Formatted result display
• Example search buttons
• Mobile-responsive design

Send POST requests to the val's URL:

curl -X POST https://your-val-url.web.val.run \
  -H "Content-Type: application/json" \
  -d '{
    "query": "find all the latest prompts mentioned",
    "targetUser": "dl4senses"
  }'

• query (required): Natural language search query
• targetUser (optional): Specific X handle to search (without @)
• dateRange (optional): Object with from and to dates (ISO8601 format)
• includeMedia (optional): Enable image/video analysis (default: false)
• maxResults (optional): Limit number of results

{
  "query": "find all the latest prompts mentioned",
  "targetUser": "dl4senses",
  "includeMedia": true
}

{
  "query": "latest AI developments and machine learning breakthroughs",
  "dateRange": {
    "from": "2025-01-01",
    "to": "2025-01-15"
  }
}

{
  "query": "popular coding tutorials",
  "maxResults": 10
}

{
  "success": true,
  "data": {
    "summary": "Comprehensive answer to your query...",
    "posts": [
      {
        "id": "1234567890",
        "text": "Post content...",
        "author": "username",
        "timestamp": "2025-01-01T12:00:00Z",
        "url": "https://x.com/username/status/1234567890"
      }
    ],
    "citations": [
      "https://x.com/username/status/1234567890"
    ],
    "metadata": {
      "model": "grok-4-fast",
      "usage": {
        "prompt_tokens": 100,
        "completion_tokens": 200,
        "total_tokens": 300
      },
      "searchTime": 2500
    }
  }
}

Set the following environment variable in your Val Town dashboard:

• XAI_API_KEY: Your xAI API key (required)

1. Create a new val in Val Town
2. Upload the files from this directory
3. Set the XAI_API_KEY environment variable
4. Test with the example requests above

This application uses:

• Model: grok-4-fast - Fast reasoning model optimized for search
• Tools: X Search with optional web search
• Rate Limits: Respects xAI API rate limits

The application returns appropriate HTTP status codes and error messages:

• 400: Bad request (invalid parameters)
• 405: Method not allowed (non-POST requests)
• 500: Internal server error (API failures)

• Input validation and sanitization
• Secure API key handling via environment variables
• CORS headers for browser compatibility
• Request logging for debugging

• Dependent on xAI API availability and rate limits
• Search results limited by X's data retention policies
• Media analysis increases token usage and response time

curl -X POST https://your-val-url.web.val.run \
  -H "Content-Type: application/json" \
  -d '{
    "query": "find all the latest prompts mentioned by @dl4senses",
    "targetUser": "dl4senses",
    "includeMedia": true,
    "dateRange": {
      "from": "2025-01-01"
    }
  }'

curl -X POST https://your-val-url.web.val.run \
  -H "Content-Type: application/json" \
  -d '{
    "query": "latest artificial intelligence news and breakthroughs",
    "dateRange": {
      "from": "2025-01-01"
    },
    "maxResults": 15
  }'

To extend this application:

1. Add new search parameters in types.ts
2. Implement additional parsing logic in grok_client.ts
3. Add new endpoint handlers in main.ts

For issues related to:

• API functionality: Check xAI documentation
• Val Town deployment: Review Val Town docs
• Application bugs: Create an issue in the repository