Xquik Tweet Search

Search recent public posts on X (Twitter) using the Xquik API

Search recent public posts on X (Twitter) in agent workflows with a single function call.

from praisonaiagents import Agent
from praisonaiagents.tools import search_x_posts

agent = Agent(name="SocialResearcher", tools=[search_x_posts])
agent.start("Find recent posts about PraisonAI on X")

The user describes a topic; the agent searches recent public X posts via Xquik and summarises highlights.

Quick Start

1. Set your API key

   export XQUIK_API_KEY=your_xquik_api_key
   export OPENAI_API_KEY=your_openai_api_key

2. Install and run

   import os
   import httpx
   from praisonaiagents import Agent
   from praisonaiagents.tools import tool
   
   XQUIK_API_KEY = os.getenv("XQUIK_API_KEY", "")
   
   def _xquik_api_key_available() -> bool:
       return bool(XQUIK_API_KEY)
   
   @tool(availability=_xquik_api_key_available)
   def search_x_posts(query: str, limit: int = 5) -> str:
       """Search recent public posts on X (Twitter) using the Xquik API.
   
       Args:
           query: Search query string.
           limit: Number of results to return (1–10, default 5).
   
       Returns:
           Formatted tweet summaries or an error message.
       """
       if not query or not query.strip():
           return "Error: query cannot be empty."
   
       limit = max(1, min(10, limit))
   
       try:
           response = httpx.get(
               "https://api.xquik.com/v1/search",
               params={"q": query, "limit": limit},
               headers={"Authorization": f"Bearer {XQUIK_API_KEY}"},
               timeout=10,
           )
           response.raise_for_status()
           data = response.json()
       except httpx.TimeoutException:
           return "Error: request timed out — try again shortly."
       except httpx.HTTPStatusError as e:
           return f"Error: HTTP {e.response.status_code} from Xquik API."
       except Exception as e:
           return f"Error: {e}"
   
       posts = data.get("results") or data.get("posts") or []
       if not posts:
           return f"No results found for '{query}'."
   
       lines = []
       for post in posts[:limit]:
           author = post.get("author", "unknown")
           text = post.get("text", "")
           tweet_id = post.get("id", "")
           lines.append(f"@{author}: {text} ({tweet_id})")
   
       return "\n".join(lines)
   
   
   agent = Agent(
       name="SocialResearcher",
       instructions="Search X for recent posts and summarise key themes.",
       tools=[search_x_posts],
   )
   
   agent.start("Find recent posts about AI agents")

How It Works

Each result line uses the format @author: text (tweet_id) so agents can reference specific posts downstream.

Configuration

Prerequisites

Function Signature

availability= decorator pattern

The @tool(availability=_xquik_api_key_available) decorator hides search_x_posts from the agent’s tool list when XQUIK_API_KEY is not set. This pattern works for any API-key-gated tool:

def _my_api_key_available() -> bool:
    return bool(os.getenv("MY_API_KEY"))

@tool(availability=_my_api_key_available)
def my_tool(...) -> str:
    ...

When the env var is absent the tool is silently omitted — no runtime error, no confusing model hallucination.

Common Patterns

Multiple queries in one agent run

agent = Agent(
    name="TrendTracker",
    instructions="Search for each topic and identify common themes.",
    tools=[search_x_posts],
)

agent.start(
    "Search for 'AI agents' and 'LLM tools' separately, then compare results."
)

Combine with a summariser

from praisonaiagents import Agent, Task, PraisonAIAgents

searcher = Agent(
    name="Searcher",
    instructions="Find recent X posts about the given topic.",
    tools=[search_x_posts],
)

summariser = Agent(
    name="Summariser",
    instructions="Summarise the key themes from the posts found.",
)

search_task = Task(
    description="Search X for 'open source LLMs'",
    agent=searcher,
    expected_output="List of tweet summaries",
)

summary_task = Task(
    description="Summarise the tweets into 3 key themes",
    agent=summariser,
    expected_output="3-point summary",
    context=[search_task],
)

PraisonAIAgents(agents=[searcher, summariser], tasks=[search_task, summary_task]).start()

Best Practices

export XQUIK_API_KEY=xq_...

Related