LLM Context

Requires API Key: Get one at https://api.search.brave.com

Plan: Included in the Search plan. See https://api-dashboard.search.brave.com/app/subscriptions/subscribe

Brave LLM Context API delivers pre-extracted, relevance-ranked web content optimized for grounding LLM responses in real-time search results. Unlike traditional web search APIs that return links and snippets, LLM Context extracts the actual page content—text chunks, tables, code blocks, and structured data—so your LLM or AI agent can reason over it directly.

LLM Context vs AI Grounding

Endpoint

GET  https://api.search.brave.com/res/v1/llm/context
POST https://api.search.brave.com/res/v1/llm/context

Authentication: X-Subscription-Token: <API_KEY> header

Optional Headers:

Accept-Encoding: gzip — Enable gzip compression

Quick Start

GET Request

curl -s "https://api.search.brave.com/res/v1/llm/context?q=tallest+mountains+in+the+world" \
  -H "Accept: application/json" \
  -H "X-Subscription-Token: ${BRAVE_SEARCH_API_KEY}"

POST Request (JSON body)

curl -s --compressed -X POST "https://api.search.brave.com/res/v1/llm/context" \
  -H "Accept: application/json" \
  -H "Accept-Encoding: gzip" \
  -H "X-Subscription-Token: ${BRAVE_SEARCH_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"q": "tallest mountains in the world"}'

With Goggles (Inline)

curl -s "https://api.search.brave.com/res/v1/llm/context" \
  -H "Accept: application/json" \
  -H "X-Subscription-Token: ${BRAVE_SEARCH_API_KEY}" \
  -G \
  --data-urlencode "q=rust programming" \
  --data-urlencode 'goggles=$discard
$site=docs.rs
$site=rust-lang.org'

Parameters

Query Parameters

| Parameter | Type | Required | Default | Description | |--|--|--|--|--| | q | string | Yes | - | Search query (1-400 chars, max 50 words) | | country | string | No | US | Search country (2-letter country code or ALL) | | search_lang | string | No | en | Language preference (2+ char language code) | | count | int | No | 20 | Max search results to consider (1-50) |

Context Size Parameters

| Parameter | Type | Required | Default | Description | |--|--|--|--|--| | maximum_number_of_urls | int | No | 20 | Max URLs in response (1-50) | | maximum_number_of_tokens | int | No | 8192 | Approximate max tokens in context (1024-32768) | | maximum_number_of_snippets | int | No | 50 | Max snippets across all URLs (1-100) | | maximum_number_of_tokens_per_url | int | No | 4096 | Max tokens per individual URL (512-8192) | | maximum_number_of_snippets_per_url | int | No | 50 | Max snippets per individual URL (1-100) |

Filtering & Local Parameters

Context Size Guidelines

| Task Type | count | max_tokens | Example | |--|--|--|--| | Simple factual | 5 | 2048 | "What year was Python created?" | | Standard queries | 20 | 8192 | "Best practices for React hooks" | | Complex research | 50 | 16384 | "Compare AI frameworks for production" |

Larger context windows provide more information but increase latency and cost (of your inference). Start with defaults and adjust.

Threshold Modes

Local Recall

The enable_local parameter controls location-aware recall:

For most use cases, omit enable_local and let the API auto-detect from location headers.

Location Headers

Priority: X-Loc-Lat + X-Loc-Long take precedence. When provided, text-based headers (City, State, Country, Postal-Code) are not used for location resolution. Provide text-based headers only when you don't have coordinates.

Example: With Coordinates

curl -s "https://api.search.brave.com/res/v1/llm/context" \
  -H "Accept: application/json" \
  -H "X-Subscription-Token: ${BRAVE_SEARCH_API_KEY}" \
  -H "X-Loc-Lat: 37.7749" \
  -H "X-Loc-Long: -122.4194" \
  -G \
  --data-urlencode "q=best coffee shops near me"

Example: With Place Name

curl -s "https://api.search.brave.com/res/v1/llm/context" \
  -H "Accept: application/json" \
  -H "X-Subscription-Token: ${BRAVE_SEARCH_API_KEY}" \
  -H "X-Loc-City: San Francisco" \
  -H "X-Loc-State: CA" \
  -H "X-Loc-Country: US" \
  -G \
  --data-urlencode "q=best coffee shops near me"

Goggles (Custom Ranking) — Unique to Brave

Goggles let you control which sources ground your LLM — essential for RAG quality.

Hosted goggles must be on GitHub/GitLab, include ! name:, ! description:, ! author: headers, and be registered at https://search.brave.com/goggles/create. Inline rules need no registration.

Syntax: $boost=N / $downrank=N (1–10), $discard, $site=example.com. Combine with commas: $site=example.com,boost=3. Separate rules with \n (%0A).

Allow list: $discard\n$site=docs.python.org\n$site=developer.mozilla.org — Block list: $discard,site=pinterest.com\n$discard,site=quora.com

Resources: Discover · Syntax · Quickstart

Response Format

Standard Response

{
  "grounding": {
    "generic": [
      {
        "url": "https://example.com/page",
        "title": "Page Title",
        "snippets": [
          "Relevant text chunk extracted from the page...",
          "Another relevant passage from the same page..."
        ]
      }
    ],
    "map": []
  },
  "sources": {
    "https://example.com/page": {
      "title": "Page Title",
      "hostname": "example.com",
      "age": ["Wednesday, January 15, 2025", "2025-01-15", "392 days ago"]
    }
  }
}

Local Response (with `enable_local`)

{
  "grounding": {
    "generic": [...],
    "poi": {
      "name": "Business Name",
      "url": "https://business.com",
      "title": "Title of business.com website",
      "snippets": ["Business details and information..."]
    },
    "map": [
      {
        "name": "Place Name",
        "url": "https://place.com",
        "title": "Title of place.com website",
        "snippets": ["Place information and details..."]
      }
    ]
  },
  "sources": {
    "https://business.com": {
      "title": "Business Name",
      "hostname": "business.com",
      "age": null
    }
  }
}

Response Fields

Note: Snippets may contain plain text OR JSON-serialized structured data (tables, schemas, code blocks). LLMs handle this mixed format well.

Use Cases

AI Agents: Give your agent a web search tool that returns ready-to-use content in a single call
RAG Pipelines: Ground LLM responses in fresh, relevant web content
AI Assistants & Chatbots: Provide factual answers backed by real sources
Question Answering: Retrieve focused context for specific queries
Fact Checking: Verify claims against current web content
Content Research: Gather source material on any topic with one API call

Best Practices

Token budget: Start with defaults (maximum_number_of_tokens=8192, count=20). Reduce for simple lookups, increase for complex research.
Source quality: Use Goggles to restrict to trusted sources. Set context_threshold_mode=strict when precision > recall.
Performance: Use smallest count and maximum_number_of_tokens that meet your needs. For local queries, provide location headers.