> ## Documentation Index
> Fetch the complete documentation index at: https://docs.scrapellm.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Grok
> Extract structured data from the Grok web interface - web sources, real X posts, follow-up questions, and three reasoning modes - as clean JSON.
**X (Twitter) posts included**
Every response includes `x_results` - real posts from X that Grok pulled in to inform its answer. No other AI scraper surfaces this data.
## Overview
Use Grok to track brand sentiment on X, monitor real-time reactions to news, and understand what the X community is saying about any topic - all grounded in Grok's AI-synthesised answer. The three reasoning modes let you trade off speed versus depth depending on your use case.
## Unique features
* **X posts**: Real posts from X (Twitter) that Grok cited - includes post text, author, view count, and timestamp
* **Web sources**: Standard web citations alongside the X posts
* **Three reasoning modes**: `AUTO`, `FAST`, and `EXPERT` for different speed/depth trade-offs
* **Related questions**: Grok's suggested follow-up questions
## Modes
| Mode | Description |
| ------------------- | ---------------------------------------------- |
| `MODEL_MODE_AUTO` | Grok selects the model automatically (default) |
| `MODEL_MODE_FAST` | Quick responses using Grok mini |
| `MODEL_MODE_EXPERT` | Deeper reasoning using the full Grok model |
## Example request
```bash cURL theme={null}
# Streaming can take up to 300s - --max-time matches the server timeout
curl --max-time 300 \
-G "https://api.scrapellm.com/scrapers/grok" \
--data-urlencode "api_key=YOUR_API_KEY" \
--data-urlencode "prompt=What are people on X saying about email marketing tools?" \
--data-urlencode "country=US" \
--data-urlencode "mode=MODEL_MODE_AUTO"
```
```python Python theme={null}
import requests
response = requests.get(
"https://api.scrapellm.com/scrapers/grok",
headers={"X-API-Key": "YOUR_API_KEY"},
params={
"prompt": "What are people on X saying about email marketing tools?",
"country": "US",
"mode": "MODEL_MODE_AUTO",
}
)
print(response.json())
```
```javascript JavaScript theme={null}
const params = new URLSearchParams({
prompt: "What are people on X saying about email marketing tools?",
country: "US",
mode: "MODEL_MODE_AUTO",
});
const response = await fetch(
`https://api.scrapellm.com/scrapers/grok?${params}`,
{ headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const data = await response.json();
```
## Response schema
Includes [common response fields](/guides/making-requests#common-response-fields) plus:
| Field | Type | Description |
| ------------------------- | ------- | ------------------------------------------------------ |
| `result` | string | Plain-text response from Grok |
| `result_markdown` | string | Markdown-formatted response |
| `web_sources` | array | Web citations - each has `title`, `url`, and `preview` |
| `web_sources[].title` | string | Article title |
| `web_sources[].url` | string | Source URL |
| `web_sources[].preview` | string | Text excerpt from the source |
| `x_results` | array | Real X posts Grok surfaced |
| `x_results[].post_id` | string | X post ID |
| `x_results[].user_name` | string | X handle (without @) |
| `x_results[].name` | string | Display name of the X user |
| `x_results[].text` | string | Full text of the post |
| `x_results[].view_count` | integer | Number of views |
| `x_results[].create_time` | string | ISO 8601 timestamp of the post |
| `related_questions` | array | Grok's suggested follow-up questions |
| `mode` | string | The reasoning mode used |
| `llm_model` | string | Grok model used (e.g. `grok-3`) |
| `credits_used` | integer | Credits consumed - always `3` for Grok |
| `elapsed_ms` | float | End-to-end request duration in milliseconds |
| `cached` | boolean | `true` if served from cache |
## Common questions
### Which countries are not supported?
JP (Japan) and TW (Taiwan) are not currently supported. Requests with these country codes will return an error.
### When should I use `MODEL_MODE_EXPERT`?
For complex research questions where depth matters more than speed - competitor analysis, in-depth market research, or multi-faceted topics. Expert mode takes longer but produces more thorough answers.
### Are X posts always present in the response?
No. X posts only appear when Grok determines they're relevant to the query. Social-focused questions like "What are people saying about X?" are more likely to surface posts than technical or factual queries.
## OpenAPI
````yaml GET /scrapers/grok
openapi: 3.1.0
info:
title: ScrapeLLM — Grok Scraper
version: 1.0.0
description: >
Scrape the real Grok (xAI) web interface via ScrapeLLM's browser pool.
Returns the full
response — including web sources, X (Twitter) posts, and follow-up
suggestions — as
structured JSON.
**Base URL:** `https://api.scrapellm.com`
**Credits:** 3 per request · 500 free credits · No credit card required
Get your API key at [scrapellm.com/signup](https://scrapellm.com/signup).
contact:
email: hello@scrapellm.com
url: https://scrapellm.com
license:
name: ScrapeLLM Terms of Service
url: https://scrapellm.com/terms
servers:
- url: https://api.scrapellm.com
description: Production
security:
- ApiKeyHeader: []
- ApiKeyQuery: []
tags:
- name: Grok Scraper
description: Submit prompts to Grok (xAI) and receive structured responses.
paths:
/scrapers/grok:
get:
tags:
- Grok Scraper
summary: Send a Grok Scraping Request
description: >
Send a prompt to Grok (xAI) via a pool of real browsers and get the full
response as
structured JSON. Blocks until Grok responds or `timeout` is reached.
Grok uniquely returns both web search results (`web_sources`) and X
(Twitter) posts
(`x_results`) relevant to the query, alongside its main answer and
follow-up
suggestions.
**Country restrictions** — JP and TW are not supported.
**Authentication** — pass your API key via the `X-API-Key` header or as
`?api_key=`
in the URL.
operationId: scrapeGrok
parameters:
- name: prompt
in: query
required: true
description: The prompt to send to Grok. Maximum 4,000 characters.
schema:
type: string
minLength: 1
maxLength: 4000
example: What is the latest news on AI?
- name: country
in: query
required: false
description: >
ISO 3166-1 alpha-2 country code. Routes the request through
infrastructure in
that region for localised responses. JP and TW are not supported.
Defaults to `US`.
schema:
type: string
minLength: 2
maxLength: 2
default: US
example: US
- name: mode
in: query
required: false
description: >
Grok reasoning mode:
- `MODEL_MODE_AUTO` — Grok selects the model automatically
(default).
- `MODEL_MODE_FAST` — Quick responses using Grok mini.
- `MODEL_MODE_EXPERT` — Deeper reasoning using the full Grok model.
schema:
type: string
enum:
- MODEL_MODE_AUTO
- MODEL_MODE_FAST
- MODEL_MODE_EXPERT
default: MODEL_MODE_AUTO
example: MODEL_MODE_AUTO
- name: bypass_cache
in: query
required: false
description: Skip the response cache and always fetch a fresh result.
schema:
type: boolean
default: false
- name: timeout
in: query
required: false
description: >-
Maximum seconds to wait for Grok to respond. Must be between 10 and
600.
schema:
type: number
format: float
minimum: 10
maximum: 600
default: 300
responses:
'200':
description: Scrape completed successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/GrokScrapeResponse'
example:
scraper: grok
status: done
job_id: job_abc123
prompt: What brands do marketers recommend for email automation?
country: US
mode: MODEL_MODE_AUTO
result: >-
Marketers commonly recommend Mailchimp, HubSpot, and
Klaviyo...
result_markdown: >-
Marketers commonly recommend **Mailchimp**, **HubSpot**, and
**Klaviyo**...
web_sources:
- title: Best Email Marketing Platforms 2025
preview: >-
We tested 12 tools across deliverability, automation, and
pricing...
url: https://example.com/email-marketing-comparison
x_results:
- post_id: '1234567890123456789'
user_name: marketingpro
name: Marketing Pro
text: >-
Switched to Klaviyo last year and revenue from email went
up 40%.
view_count: 84200
profile_image_url: https://pbs.twimg.com/profile_images/example.jpg
create_time: '2025-11-02T14:32:00Z'
related_questions:
- What is the best email automation tool for e-commerce?
- How does Klaviyo compare to Mailchimp?
conversation:
conversation_id: conv_abc123
title: Email Automation Tools
temporary: true
create_time: '2026-03-18T12:00:00Z'
modify_time: '2026-03-18T12:00:05Z'
llm_model: grok-3
credits_used: 3
elapsed_ms: 7841.2
cached: false
markdown_url: https://scrapellm.com/md/job_abc123.md
'401':
description: Missing or invalid API key.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
detail: >-
Missing API key. Pass your key in the X-API-Key header or as
?api_key= in the URL.
'429':
description: Credit limit reached or scraper queue is full — retry shortly.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: Scraper returned an empty or unexpected result — safe to retry.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'502':
description: Grok execution failed on the upstream scraper — safe to retry.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'503':
description: Scraper pool is still warming up — retry in a few seconds.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'504':
description: Network timeout reaching the scraper machine.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
x-codeSamples:
- lang: Shell
label: cURL
source: >
# Streaming can take up to 300s - --max-time matches the server
timeout
curl --max-time 300 \
-G "https://api.scrapellm.com/scrapers/grok" \
--data-urlencode "api_key=YOUR_API_KEY" \
--data-urlencode "prompt=What are people on X saying about email marketing tools?" \
--data-urlencode "country=US" \
--data-urlencode "mode=MODEL_MODE_AUTO"
- lang: Python
label: Python
source: |
import requests
response = requests.get(
"https://api.scrapellm.com/scrapers/grok",
params={
"api_key": "YOUR_API_KEY",
"prompt": "What are people on X saying about email marketing tools?",
"country": "US",
"mode": "MODEL_MODE_AUTO",
}
)
print(response.json())
- lang: JavaScript
label: JavaScript
source: |
const params = new URLSearchParams({
api_key: "YOUR_API_KEY",
prompt: "What are people on X saying about email marketing tools?",
country: "US",
mode: "MODEL_MODE_AUTO",
});
const response = await fetch(
`https://api.scrapellm.com/scrapers/grok?${params}`
);
const data = await response.json();
console.log(data);
- lang: TypeScript
label: TypeScript
source: |
const params = new URLSearchParams({
api_key: "YOUR_API_KEY",
prompt: "What are people on X saying about email marketing tools?",
country: "US",
mode: "MODEL_MODE_AUTO",
});
const response = await fetch(
`https://api.scrapellm.com/scrapers/grok?${params}`
);
const data = await response.json();
console.log(data);
components:
schemas:
GrokScrapeResponse:
type: object
required:
- scraper
- status
- job_id
- prompt
- country
- mode
- result
- credits_used
- elapsed_ms
- cached
properties:
scraper:
type: string
description: Always `"grok"`.
example: grok
status:
type: string
description: '`"done"` on success.'
example: done
job_id:
type: string
description: Unique identifier for this scrape job.
example: job_abc123
prompt:
type: string
description: The prompt that was submitted.
example: What brands do marketers recommend for email automation?
country:
type: string
description: The country the request was routed through.
example: US
mode:
type: string
description: The Grok reasoning mode used for this request.
enum:
- MODEL_MODE_AUTO
- MODEL_MODE_FAST
- MODEL_MODE_EXPERT
example: MODEL_MODE_AUTO
result:
type: string
description: Plain-text response from Grok.
example: Marketers commonly recommend Mailchimp, HubSpot, and Klaviyo...
result_markdown:
type: string
nullable: true
description: Markdown-formatted response from Grok.
example: >-
Marketers commonly recommend **Mailchimp**, **HubSpot**, and
**Klaviyo**...
web_sources:
type: array
description: >-
Web pages cited by Grok, each with a title, preview snippet, and
URL.
items:
$ref: '#/components/schemas/GrokWebSource'
x_results:
type: array
description: >
X (Twitter) posts surfaced by Grok's native X search integration.
This is unique
to Grok among all major LLMs.
items:
$ref: '#/components/schemas/GrokXResult'
related_questions:
type: array
description: Follow-up questions suggested by Grok.
items:
type: string
example:
- What is the best email automation tool for e-commerce?
- How does Klaviyo compare to Mailchimp?
conversation:
$ref: '#/components/schemas/GrokConversation'
llm_model:
type: string
nullable: true
description: Grok model variant used (e.g. `grok-3`).
example: grok-3
credits_used:
type: integer
description: Credits consumed by this request. Always `3` for Grok.
example: 3
elapsed_ms:
type: number
format: float
description: Total end-to-end request duration in milliseconds.
example: 7841.2
cached:
type: boolean
description: '`true` if this response was served from cache.'
example: false
markdown_url:
type: string
nullable: true
description: |
Hosted `.md` URL for this response. Expires after 24 hours.
example: https://scrapellm.com/md/job_abc123.md
ErrorResponse:
type: object
required:
- detail
properties:
detail:
type: string
description: Human-readable description of the error.
example: Invalid API key.
GrokWebSource:
type: object
required:
- title
- url
properties:
title:
type: string
description: Title of the cited web page.
example: Best Email Marketing Platforms 2025
preview:
type: string
nullable: true
description: Short excerpt or preview text from the cited page.
example: We tested 12 tools across deliverability, automation, and pricing...
url:
type: string
format: uri
description: Absolute URL of the cited source.
example: https://example.com/email-marketing-comparison
GrokXResult:
type: object
required:
- post_id
- user_name
- name
- text
- view_count
properties:
post_id:
type: string
description: X (Twitter) post ID.
example: '1234567890123456789'
user_name:
type: string
description: X handle of the post author, without the `@` prefix.
example: marketingpro
name:
type: string
description: Display name of the X user.
example: Marketing Pro
text:
type: string
description: Full text content of the X post.
example: Switched to Klaviyo last year and revenue from email went up 40%.
view_count:
type: integer
description: Number of views on the post.
example: 84200
profile_image_url:
type: string
format: uri
nullable: true
description: URL of the user's profile image.
example: https://pbs.twimg.com/profile_images/example.jpg
create_time:
type: string
format: date-time
nullable: true
description: ISO 8601 timestamp when the post was created.
example: '2025-11-02T14:32:00Z'
GrokConversation:
type: object
nullable: true
description: Metadata about the underlying Grok conversation session.
properties:
conversation_id:
type: string
description: Internal conversation identifier.
example: conv_abc123
title:
type: string
nullable: true
description: Title Grok assigned to the conversation.
example: Email Automation Tools
temporary:
type: boolean
description: Whether the conversation is marked as temporary.
example: true
create_time:
type: string
format: date-time
nullable: true
description: ISO 8601 timestamp when the conversation was created.
example: '2026-03-18T12:00:00Z'
modify_time:
type: string
format: date-time
nullable: true
description: ISO 8601 timestamp of the last modification.
example: '2026-03-18T12:00:05Z'
securitySchemes:
ApiKeyHeader:
type: apiKey
in: header
name: X-API-Key
description: Your ScrapeLLM API key passed in the request header.
ApiKeyQuery:
type: apiKey
in: query
name: api_key
description: Your ScrapeLLM API key passed as a query parameter.
````