# Grok Live Search Tool — Real-Time Web Grounding via API

> Grok Live Search grounds output in fresh web/X/news inside one API call. Whitelist sources, set max results, get inline citations.

## Install

Save the content below to `.claude/skills/` or append to your `CLAUDE.md`:

## Quick Use

1. Add `extra_body={'search_parameters': {'mode':'on','sources':[{'type':'web'}]}}` to chat.completions.create
2. Read `message.citations` to render footnotes
3. Cache by (query, sources, date_range) hash

---

## Intro

Grok Live Search is a server-side tool baked into xAI's API that grounds Grok's response on fresh web, X (Twitter), and news results without an external retrieval pipeline. You set `mode=on/auto`, choose source types, and Grok handles search + read + cite. Returns inline citations plus a `num_sources_used` field. Best for: news Q&A, finance/sports/election apps, anywhere the answer must reflect today's reality. Works with: any OpenAI-compatible client (Python, JS, curl) hitting api.x.ai. Setup time: 2 minutes.

---

### Curl example

```bash
curl https://api.x.ai/v1/chat/completions \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-3",
    "messages": [{"role":"user","content":"Top 3 AI funding rounds this week, with amounts and lead investors"}],
    "search_parameters": {
      "mode": "on",
      "sources": [{"type":"web"},{"type":"news"},{"type":"x"}],
      "max_search_results": 10,
      "from_date": "2026-05-01",
      "to_date":   "2026-05-08"
    }
  }'
```

### Python with date range + X handle filter

```python
resp = client.chat.completions.create(
    model="grok-3",
    messages=[{"role": "user", "content": "What is @sama tweeting about OpenAI's new release?"}],
    extra_body={
        "search_parameters": {
            "mode": "on",
            "sources": [
                {"type": "x", "x_handles": ["sama"]},
            ],
            "from_date": "2026-05-05",
            "max_search_results": 5,
        }
    },
)
```

### Source types

| Type | Filters | What it queries |
|---|---|---|
| `web` | none | Public web search index |
| `news` | none | News article corpus |
| `x` | `x_handles[]` | X (Twitter) posts |
| `rss` | `links[]` | Specific RSS feeds you supply |

### Modes

- `off` — pure model knowledge cutoff (default)
- `auto` — Grok decides whether to search based on the question
- `on` — always search (use for news/finance/sports/election queries)

### Response surface

```python
resp.choices[0].message.content       # grounded answer
resp.choices[0].message.citations     # list of {url, title, source_type}
resp.usage.num_sources_used           # how many results actually informed the answer
```

---

### FAQ

**Q: Cost of Live Search?**
A: Per-search billing on top of token cost — typically a few cents per call depending on `max_search_results`. Check console.x.ai for current rates. Cheaper than running your own search + scraper + chunker.

**Q: Does it replace Tavily / Exa / Perplexity API?**
A: For Grok users, mostly yes — search + grounding in one call, fewer moving parts. Tavily/Exa are model-agnostic so still useful when your stack is multi-model. Perplexity API competes head-on; Grok wins on long-context, Perplexity wins on academic/citation depth.

**Q: How do I cache results to save cost?**
A: Hash the (query, source_filter, date_range) triple as a cache key, store the response with a TTL matching your freshness needs (5 min for finance, 1 hour for general news). xAI doesn't cache server-side.

---

## Source & Thanks

> Built by [xAI](https://x.ai). Live Search docs at [docs.x.ai/docs/guides/live-search](https://docs.x.ai/docs/guides/live-search).
>
> Public SDK: [xai-org](https://github.com/xai-org)

---

<!-- ZH -->

## 快速使用

1. chat.completions.create 加 `extra_body={'search_parameters': {'mode':'on','sources':[{'type':'web'}]}}`
2. 读 `message.citations` 渲染脚注
3. 按 (query, sources, date_range) hash 缓存

---

## 简介

Grok Live Search 是 xAI API 内置的服务端工具，把 Grok 响应 grounding 在新鲜 web、X（Twitter）、news 结果上 —— 不用搭外部 retrieval 流水线。设 `mode=on/auto`、选源类型，Grok 自己 search + read + cite。返回内联引用和 `num_sources_used` 字段。适合新闻问答、金融/体育/选举应用、任何答案必须反映当下现实的场景。兼容任何 OpenAI 兼容客户端（Python / JS / curl）打 api.x.ai。装机时间 2 分钟。

---

### Curl 例子

```bash
curl https://api.x.ai/v1/chat/completions \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-3",
    "messages": [{"role":"user","content":"本周 AI 融资 Top 3：金额 + 领投方"}],
    "search_parameters": {
      "mode": "on",
      "sources": [{"type":"web"},{"type":"news"},{"type":"x"}],
      "max_search_results": 10,
      "from_date": "2026-05-01",
      "to_date":   "2026-05-08"
    }
  }'
```

### Python 带日期范围 + X 账号筛选

```python
resp = client.chat.completions.create(
    model="grok-3",
    messages=[{"role": "user", "content": "@sama 在 X 上怎么聊 OpenAI 最新发布？"}],
    extra_body={
        "search_parameters": {
            "mode": "on",
            "sources": [
                {"type": "x", "x_handles": ["sama"]},
            ],
            "from_date": "2026-05-05",
            "max_search_results": 5,
        }
    },
)
```

### 源类型

| 类型 | 筛选 | 检索什么 |
|---|---|---|
| `web` | 无 | 公网搜索索引 |
| `news` | 无 | 新闻文章语料 |
| `x` | `x_handles[]` | X（Twitter）posts |
| `rss` | `links[]` | 指定的 RSS feed |

### 模式

- `off` —— 纯模型知识截止（默认）
- `auto` —— Grok 自己决定要不要 search
- `on` —— 总是 search（新闻 / 金融 / 体育 / 选举类问题用）

### 响应字段

```python
resp.choices[0].message.content       # grounding 后答案
resp.choices[0].message.citations     # {url, title, source_type} 列表
resp.usage.num_sources_used           # 实际几个结果参与了答案
```

---

### FAQ

**Q: Live Search 成本？**
A: 在 token 成本之上按搜索次数计费 —— 通常每次调用几美分，看 `max_search_results`。具体费率看 console.x.ai。比自己跑 search + scraper + chunker 便宜。

**Q: 替代 Tavily / Exa / Perplexity API 吗？**
A: Grok 用户基本是 —— 一次调用 search + grounding，零件更少。Tavily/Exa 模型无关，多模型栈还有用。Perplexity API 直接对打：Grok 长上下文赢，Perplexity 学术引用深度赢。

**Q: 怎么缓存结果省钱？**
A: 把 (query, source_filter, date_range) 三元组 hash 当 cache key，按新鲜度需求设 TTL（金融 5 分钟、一般新闻 1 小时）存响应。xAI 服务端不缓存。

---

## 来源与感谢

> Built by [xAI](https://x.ai). Live Search docs at [docs.x.ai/docs/guides/live-search](https://docs.x.ai/docs/guides/live-search).
>
> Public SDK: [xai-org](https://github.com/xai-org)


---
Source: https://tokrepo.com/en/workflows/grok-live-search-tool-real-time-web-grounding-via-api
Author: xAI