X (Twitter) Search Integration for Hermes Agent

hermes tools
# → 🐦 X (Twitter) Search (press space to toggle on)

# ~/.hermes/config.yaml
x_search:
  # xAI model used for the Responses call.
  # grok-4.5 is the recommended default; any Grok model
  # with x_search tool access works.
  model: grok-4.5

  # Optional reasoning effort: low, medium, high, or xhigh. When omitted,
  # the selected model's default applies. xhigh is supported only by
  # models that document it, such as grok-4.20-multi-agent.
  # reasoning_effort: low

  # Request timeout in seconds. x_search can take 60, 120s for
  # complex queries, the default is generous. Minimum: 30.
  timeout_seconds: 180

  # Number of automatic retries on 5xx / ReadTimeout / ConnectionError.
  # Each retry backs off (1.5x attempt seconds, capped at 5s).
  retries: 2

Configuration Reference

Option	Type	Default	Description
model	string	grok-4.5	xAI model used for the Responses call. Any Grok model with x_search tool access works.
reasoning_effort	string	model default	Optional reasoning effort: low, medium, high, or xhigh. xhigh is supported only by models that document it, such as grok-4.20-multi-agent.
timeout_seconds	integer	180	Request timeout in seconds. Minimum: 30. x_search can take 60, 120s for complex queries.
retries	integer	2	Number of automatic retries on 5xx / ReadTimeout / ConnectionError. Each retry backs off (1.5x attempt seconds, capped at 5s).

Tool parameters

The agent calls x_search with these arguments:

Parameter	Type	Description
query	string (required)	What to look up on X.
allowed_x_handles	string array	Optional list of handles to include exclusively (max 10). Leading @ is stripped.
excluded_x_handles	string array	Optional list of handles to exclude (max 10). Mutually exclusive with allowed_x_handles.
from_date	string	Optional YYYY-MM-DD start date.
to_date	string	Optional YYYY-MM-DD end date.
enable_image_understanding	boolean	Ask xAI to analyze images attached to matching posts.
enable_video_understanding	boolean	Ask xAI to analyze videos attached to matching posts.

Date validation

from_date / to_date are validated client-side before the HTTP call:

• Both, if provided, must parse as YYYY-MM-DD.
• When both are set, from_date must be on or before to_date.
• from_date must not be later than today UTC, no posts can exist in a window that hasn't started yet, so the call would be guaranteed to return zero citations.
• to_date in the future is allowed (callers may legitimately request "from yesterday to tomorrow" to catch posts as they arrive).

Validation failures surface as a structured {"error": "..."} tool result, never as an HTTP call to xAI.

How It Works

x_search is backed by xAI's built-in x_search tool on the Responses API at https://api.x.ai/v1/responses. Grok itself runs the search server-side and returns synthesized results with citations to the originating posts.

The tool's check_fn runs the xAI credential resolver every time the model's tool list is rebuilt. A True return means the bearer is fetchable AND non-empty AND (if it had expired) successfully refreshed. Revoked tokens with a failed refresh hide the tool from the schema; the model simply can't see it.

When the agent calls x_search, it sends the parameters to the xAI Responses API. The API returns a JSON response with the fields described above. The agent then uses the answer and citations to reply to the user.

x_search vs xurl

Hermes can expose two different X surfaces:

Surface	Use it for	Do not use it for
x_search	Read-only public X discovery: current discussion, reactions, claims, profiles, threads, and synthesized answers with citations.	Posting, replying, liking, DMs, media upload, deleting, or proving that an authenticated X account changed state.
xurl skill	Exact or authenticated X API work: post, reply, read, like, dm, timelines, mentions, media upload, account-specific reads, and raw v2 endpoints.	Broad Grok-synthesized public X research when x_search is available and no authenticated account context is needed.

For mixed workflows, use x_search to discover candidate public posts, then switch to xurl read or another exact xurl command after the target post/user/action is clear. Any state-changing X action must be confirmed by xurl output or the X API response; an x_search answer is never evidence that a write happened.

Requirements and Limitations

• Requires xAI credentials: either a SuperGrok / X Premium+ OAuth token or a paid xAI API key (XAI_API_KEY).
• The tool auto-enables when credentials are present, but can be disabled via hermes tools.
• The x_search tool is specifically for read-only public X discovery. It cannot post, reply, like, DM, upload media, delete, or prove that an authenticated X account changed state.
• The allowed_x_handles and excluded_x_handles parameters are mutually exclusive.
• Maximum of 10 handles for allowed_x_handles or excluded_x_handles.
• Date validation is client-side; from_date must not be later than today UTC.
• to_date in the future is allowed.
• The reasoning_effort parameter is optional and only supported by models that document it (e.g., grok-4.20-multi-agent for xhigh). Invalid values fail before an API request is made.
• The degraded flag indicates that filters were set but no citations were returned, meaning the answer is unsourced.
• xAI index gaps may cause some active accounts to intermittently fail to surface in x_search even when they post regularly.

Troubleshooting

"No xAI credentials available"

The tool surfaces this when both auth paths fail. Either set XAI_API_KEY in ~/.hermes/.env or run hermes auth add xai-oauth and complete the browser login. Then restart your session so the agent re-reads the tool registry.

"x_search is not enabled for this model"

The configured x_search.model doesn't have access to the server-side x_search tool. Switch to grok-4.5 (the default) or another Grok model that supports it. Check the xAI documentation for the current list.

Tool doesn't appear in the schema

Two possible causes:

1. Toolset not enabled. Run hermes tools and confirm 🐦 X (Twitter) Search is checked.
2. No xAI credentials. The check_fn returns False, so the schema stays hidden. Run hermes auth status to confirm xai-oauth login state, and check that XAI_API_KEY is set (if you're using the API-key path).

degraded: true, answer with no citations

When you used allowed_x_handles, excluded_x_handles, or a date range and the response comes back with degraded: true, xAI's X index returned no matching posts but Grok still produced a synthesized answer from its own training data. The answer is unsourced, do not treat it as a real X result.

Causes worth checking:

• Typo in the handle. Strip the @, double-check spelling, and confirm the account exists.
• Date range too narrow or sliding past today's posts; widen and retry.
• xAI index gap. Some active accounts intermittently fail to surface in x_search even when they post regularly. Retry after a few minutes, or use the xurl skill for direct X API reads when you need an exact handle's timeline.