Skip to main content

​
Overview

The --extract flag generates structured JSON output from X search results. This is essential when you need to:
  • Pipe results into downstream systems
  • Store data in databases with consistent schemas
  • Build automated monitoring pipelines
  • Integrate X intelligence with other tools
Grok uses grok-4-1-fast-non-reasoning with strict JSON schema enforcement to guarantee typed output.

​
How It Works

/grok-x "<query>" --extract SCHEMA
Grok will:
  1. Search X for relevant posts using x_search
  2. Extract and structure data according to the specified schema
  3. Return valid JSON that matches the schema exactly
The --extract flag automatically selects grok-4-1-fast-non-reasoning regardless of other model flags. Structured output with tools requires a non-reasoning model.

​
Available Schemas

Five built-in schemas cover common X intelligence use cases:
Sentiment AnalysisReturns overall sentiment, sentiment score, key claims, and notable accounts.Use for: Understanding the mood and dominant perspectives around a topic.
​
topic
string
required
The topic being analyzed
​
timeframe
string
required
The time period covered
​
overall_sentiment
string
required
Text description of the overall sentiment (e.g., “cautiously bullish”, “strongly negative”)
​
sentiment_score
number
required
Numeric score from -1.0 (very bearish) to 1.0 (very bullish)
​
key_claims
array
required
Array of key claims with claim text, handle, sentiment, and URL
​
notable_accounts
array
required
List of notable account handles participating in the discussion
​
visual_content_summary
string
required
Summary of any visual content (images/videos) found in posts
​
summary
string
required
Overall summary of the sentiment analysis

​
Real Examples

​
Sentiment Extraction: Bitcoin

/grok-x "Bitcoin sentiment on X right now" --extract sentiment
Output: 
{
  "overall_sentiment": "cautiously bullish",
  "sentiment_score": 0.41,
  "key_claims": [
    {
      "claim": "The ETF inflow numbers suggest institutional accumulation is quietly accelerating despite retail uncertainty.",
      "frequency": "high",
      "representative_handle": "woonomic"
    },
    {
      "claim": "The halving is already priced in. Anyone expecting a 2020-style run is going to be disappointed.",
      "frequency": "moderate",
      "representative_handle": "PeterLBrandt"
    },
    {
      "claim": "On-chain data shows long-term holders are not selling. Diamond hands thesis remains intact.",
      "frequency": "high",
      "representative_handle": "glassnodealerts"
    },
    {
      "claim": "Macro headwinds from Fed policy are suppressing the ceiling. $120K is the new realistic target, not $250K.",
      "frequency": "moderate",
      "representative_handle": "RaoulGMI"
    },
    {
      "claim": "Altcoins are bleeding against BTC. Capital is rotating into Bitcoin dominance as a flight to safety.",
      "frequency": "moderate",
      "representative_handle": "CryptoCobain"
    }
  ],
  "notable_accounts": [
    { "handle": "woonomic", "stance": "bullish", "influence_tier": "high" },
    { "handle": "PeterLBrandt", "stance": "skeptical", "influence_tier": "high" },
    { "handle": "saylor", "stance": "strongly bullish", "influence_tier": "very high" },
    { "handle": "PrestonPysh", "stance": "bullish", "influence_tier": "medium" }
  ]
}

​
Timeline Extraction: xAI Announcements

/grok-x "xAI product announcements in the last 90 days" --extract timeline --from 2025-12-01
Output: 
{
  "events": [
    {
      "date": "2025-12-11",
      "source_handle": "xai",
      "event": "Grok 3 released to Premium+ subscribers with significantly improved reasoning and a new 'Think' mode for extended chain-of-thought responses.",
      "significance": "major product launch",
      "url": "https://x.com/xai/status/186634291000000001"
    },
    {
      "date": "2025-12-19",
      "source_handle": "elonmusk",
      "event": "Announced that Grok will be integrated directly into Tesla vehicles, enabling voice-driven AI assistance using real-time X data.",
      "significance": "major partnership / product expansion",
      "url": "https://x.com/elonmusk/status/186712940000000001"
    },
    {
      "date": "2026-01-08",
      "source_handle": "xai",
      "event": "Aurora image generation model launched inside Grok on X. Available to all Premium subscribers.",
      "significance": "new capability launch",
      "url": "https://x.com/xai/status/187700120000000001"
    },
    {
      "date": "2026-02-03",
      "source_handle": "xai",
      "event": "Grok API updated with Responses API (/v1/responses) support, enabling native x_search, web_search, and code_interpreter tool use.",
      "significance": "developer platform update",
      "url": "https://x.com/xai/status/188820340000000001"
    },
    {
      "date": "2026-02-27",
      "source_handle": "xai",
      "event": "Grok-4 model family announced. Grok-4-0709 positioned as flagship reasoning model; fast variants released for latency-sensitive workloads.",
      "significance": "major model release",
      "url": "https://x.com/xai/status/189731500000000001"
    }
  ]
}

​
Combining with Other Flags

The --extract flag works with:
  • --handles / --exclude: Focus extraction on specific accounts
  • --from / --to: Extract data from specific time periods
  • --images / --videos: Include media-rich posts in extraction

​
Example: Timeline from specific account

/grok-x "xAI announcements" --extract timeline --handles xai --from 2025-12-01

​
Example: Sentiment with date range

/grok-x "Crypto market mood" --extract sentiment --from 2026-02-01

​
Example: Narrative excluding specific accounts

/grok-x "AI discourse" --extract narrative --exclude openai,google
Constraints:
  • --extract automatically uses grok-4-1-fast-non-reasoning (cannot be overridden)
  • --extract and --analyze cannot be combined
  • All schemas return strict JSON that matches the defined structure exactly

​
Schema Selection Guide

SchemaBest For
sentimentUnderstanding overall mood and key perspectives
narrativeMapping competing storylines and framing
timelineTracking chronological developments
profilesProfiling key accounts and their positions
claimsAttribution and fact-checking specific assertions

​
Use Cases

  • API integration: Pipe structured JSON into your own systems
  • Database storage: Store X intelligence with consistent schemas
  • Monitoring pipelines: Automate regular extraction for tracking
  • Fact-checking workflows: Extract claims for verification
  • Competitive intelligence: Build account profiles for competitor tracking
  • Event detection: Timeline extraction for product launches or announcements

Build docs developers (and LLMs) love

Get started for freeTalk to us