Retrieve X/Twitter context with Haystack

Xquik is an independent third-party service. Not affiliated with X Corp. "Twitter" and "X" are trademarks of X Corp.

Haystack web search components for retrieving public X/Twitter context through the Xquik REST API.

Read the Xquik Haystack guide.

This package is maintained by Xquik as a standalone Haystack integration. It follows the haystack_integrations namespace convention and exposes read-only components under:

from haystack_integrations.components.websearch.xquik import XquikTweetSearch, XquikUserTweetsFetcher

Available components

• XquikTweetSearch: calls GET /x/tweets/search and returns matching posts as Haystack Document objects.
• XquikUserTweetsFetcher: calls GET /x/users/{id}/tweets and returns recent public posts for a user as Haystack Document objects.

Both components:

• read the API key from XQUIK_API_KEY by default
• accept haystack.utils.Secret for explicit API key injection
• send the x-api-key and xquik-api-contract: 2026-04-29 headers
• keep base_url configurable for tests and controlled deployments
• return documents, links, has_more, and next_cursor

Install

Install from PyPI:

pip install xquik-haystack

Search public X data

Search posts

from haystack import Pipeline
from haystack.utils import Secret
from haystack_integrations.components.websearch.xquik import XquikTweetSearch

search = XquikTweetSearch(api_key=Secret.from_env_var("XQUIK_API_KEY"), top_k=10)

pipeline = Pipeline()
pipeline.add_component("x_search", search)

result = pipeline.run({"x_search": {"query": "haystack ai"}})
documents = result["x_search"]["documents"]

Fetch user posts

from haystack.utils import Secret
from haystack_integrations.components.websearch.xquik import XquikUserTweetsFetcher

fetcher = XquikUserTweetsFetcher(api_key=Secret.from_env_var("XQUIK_API_KEY"))

result = fetcher.run(user_id="example_user", include_replies=False)
documents = result["documents"]

Document mapping

Each tweet becomes a Haystack Document.

• Document.content: tweet text, or an empty string when text is missing
• Document.meta["endpoint"]: Xquik endpoint family used by the component
• Document.meta["id"]: tweet ID when present
• Document.meta["url"]: tweet URL when present
• Document.meta["created_at"]: tweet creation time when present
• Document.meta["author"]: author ID, username, display name, and verification status when present
• Document.meta also includes available public metrics such as like, repost, reply, quote, view, and bookmark counts

Development

This project uses Hatch for build and environment management.

pip install hatch
hatch run fmt-check
hatch run test:unit
hatch build

Unit tests mock all Xquik HTTP calls. Integration tests can be added later behind an XQUIK_API_KEY check.

Publishing

The release workflow publishes to PyPI with trusted publishing when a GitHub release is published.

Haystack merged the Xquik integration-directory listing.

License

xquik-haystack is distributed under the terms of the Apache-2.0 license.