Does x_search require a SuperGrok subscription?

Yes. xAI gates the x_search Responses API behind an active SuperGrok subscription, even after a successful OAuth handshake. Without one, calls return HTTP 403. The xitter skill is the free fallback for X search.

What is the xitter skill?

A Hermes-bundled skill that scrapes x.com HTML directly. Slower than x_search (~100-120s vs ~3-5s) and more fragile against X anti-scrape defenses, but free and enabled by default. The agent falls back to xitter automatically when x_search fails.

What is the manual paste step for?

The PKCE OAuth callback at 127.0.0.1:56121 cannot reach the container loopback listener from your laptop browser. The --manual-paste flag prints the authorize URL, you approve in your browser, and xAI shows the authorization code in a gray box on the Could not establish connection page. Copy that code and paste it back into the Terminal prompt.

← Home

Guide

Hermes Agent + X (Twitter) Search: Use x_search and the xitter Skill

Q: Why does Hermes ask for X_API_KEY when I run x_search?

Those prompts are for a separate legacy Twitter v2 Developer API integration, not for x_search. Press Enter to skip each one - x_search only needs the xAI OAuth credential.

From Hermes Agent v0.14.0, x_search is a first-class tool that lets the agent search X (Twitter) posts, threads, and profiles directly from chat. Backed by xAI’s built-in x_search Responses API — Grok runs the search server-side and returns synthesized results with citations. If you don’t have a SuperGrok subscription, the bundled xitter skill scrapes X directly and works for free.

Two Paths to X Search in Hermes

Path	How it works	Speed	Cost
`x_search`	Calls xAI’s Responses API; Grok searches X and synthesizes a cited answer.	~3–5s	Requires active SuperGrok subscription (OAuth) or paid XAI_API_KEY
`xitter` skill	Hermes-bundled skill that scrapes x.com HTML directly.	~100–120s	Free (built in)

Both end at “the agent can answer questions about X.” x_search is faster and returns Grok-quality synthesis with first-class citations. xitteris slower and more fragile (X aggressively rate-limits anonymous scrapers) but free and already enabled by default.

Use Cases

News + reactions — “What are people on X saying about the new OpenAI launch?”
Founder threads — “Find @sama’s recent threads about agent frameworks.”
Sentiment scans — “How is X reacting to the new pricing model?”
Topic tracking — “Pull posts about ‘hermes agent’ from the last 7 days.”

Path 1: x_search via SuperGrok OAuth

Requirement: an active SuperGrok subscription on the xAI account you sign in with. xAI’s Responses API returns HTTP 403 — “no active Grok subscription” — for accounts without one, even after a successful OAuth handshake. Subscribe at x.ai/grok.

Quickstart — ~60 seconds

Open your instance on the Dashboard, click the Terminal button. In the Terminal, run:
```
hermes auth add xai-oauth --manual-paste
```
Hermes prints an auth.x.ai/authorize?... URL. Open it in your laptop browser and sign in with your SuperGrok account.
On the “Could not establish connection” page, copy the authorization code from the gray box (xAI displays it explicitly — you don’t need the URL from the address bar). Paste it at the Terminal’s Callback URL: prompt and press Enter.
Enable the toolset:
```
hermes tools
```
Press 10 to toggle 🐦 X (Twitter) Search on, then press Enter to save.

Ask the agent something X-related:

hermes chat -q "Find @anthropicai’s recent posts about Claude Opus on X"

The chat may prompt for X_API_KEY, X_API_SECRET, X_BEARER_TOKEN, and similar Twitter v2 developer credentials. These are for a separate legacy Twitter API integration, NOT for x_search. Press Enter to skip each one — x_search only needs the xAI OAuth credential you just added.

What x_search Does

Hermes calls xAI’s server-side x_search tool on the Responses API at https://api.x.ai/v1/responses. Grok runs the actual search, synthesizes the answer, and returns citations to the originating posts. Your agent receives text + citations — not a raw post stream. Use x_search instead of web_search when you specifically want current discussion, reactions, or claims on X.

Why SuperGrok OAuth (instead of an API key)

x_search hits xAI’s Responses API with your bearer token. SuperGrok OAuth gives Hermes a token bound to your subscription quota — the same way Claude Pro and ChatGPT Pro OAuth route through subscription instead of paid API spend. No separate xAI API billing line item, no API key to rotate, just sign in. (If you prefer pay-per-use, XAI_API_KEY from console.x.ai also works.)

Tool Parameters

Parameter	Type	Purpose
`query`	string	Required. What to search on X.
`allowed_x_handles`	string[]	Up to 10. Restrict to specific accounts.
`excluded_x_handles`	string[]	Up to 10. Mutually exclusive with allowed_x_handles.
`from_date` / `to_date`	YYYY-MM-DD	Date window.
`enable_image_understanding`	bool	Have Grok analyze attached images.
`enable_video_understanding`	bool	Same for videos.

Configuration

# ~/.hermes/config.yaml
x_search:
  model: grok-4.20-reasoning   # default; needs server-side x_search access
  timeout_seconds: 180         # min 30; complex queries take 60-120s
  retries: 2                   # 5xx / timeout backoff

Path 2: xitter Skill (Free, No Subscription)

If you don’t have SuperGrok, the bundled xitter skill handles X search by scraping x.com HTML directly. It’s enabled by default on Hermes Agent v0.14.0 instances — no setup required. Just ask:

hermes chat -q "Find @anthropicai’s recent posts about Claude Opus on X"

The agent will try x_search first; on a 403 it falls back to xitter. Expect ~100–120 seconds for the scraper to run (much slower than x_search’s ~3–5s), and occasional failures when X’s anti-scrape defenses tighten. For one-off queries this is fine; for production agents that need reliable X access, SuperGrok OAuth or a paid XAI_API_KEY is the better path.

Example Prompts

“Pull reactions on X to the latest Anthropic launch, posts from 2026-05-10 onward.”
“Search X for ‘OpenClaw’, exclude @spammybot1 and @spammybot2.”
“Find threads from @sama about agent frameworks in the last 7 days.”
“What is @elonmusk saying about xAI today? Include attached images.”

Troubleshooting

HTTP 403 — “no active Grok subscription”

Your OAuth credential is valid but xAI is gating the API call. Check your subscription at grok.com/?_s=usage and subscribe to SuperGrok at x.ai/grok if needed. The agent will automatically fall back to xitter while you sort this out.

Tool isn’t in the model’s schema

Toolset off — run hermes tools and toggle 🐦 X (Twitter) Search on.
No xAI credentials — x_search stays hidden until a cred path resolves. Re-run hermes auth add xai-oauth --manual-paste.
Token revoked — the schema auto-hides on a failed refresh. Re-run the OAuth add.
Wrong model — needs grok-4.20-reasoning (or another xAI model with server-side x_search access).

State mismatch on manual paste

xAI’s “Could not establish connection” page surfaces only the authorization code in a gray box — not the OAuth state parameter. Hermes’ bare-code paste path is intentional support for this UX (PKCE’s code_verifier still binds the token exchange, so CSRF is mitigated). If you see “state mismatch” on a fresh attempt, you may be on an older Hermes build — bump to v0.14.0 with the upstream PR #28358 manual-paste cherry-pick.

What’s Next?

Hermes Agent + Grok — use Grok models for chat (separate from x_search server-side calls)
Hermes Agent + MCP — extend your agent with MCP tool servers alongside x_search
Hermes Agent Skills — more on the skill system (xitter is one of many bundled skills)