---
source_url: "https://github.com/brave/brave-search-skills/blob/main/skills/llm-context/SKILL.md"
title: brave-search-skills/skills/llm-context/SKILL.md at main · brave/brave-search-skills · GitHub
mirrored_at: 2026-08-31T03:02:24.525Z
host: github.com
cited_in_42a: true
mirror_canonical: "https://index.42a.ai/github.com/brave/brave-search-skills/blob/main/skills/llm-context/SKILL.md"
---

> **Original source:** https://github.com/brave/brave-search-skills/blob/main/skills/llm-context/SKILL.md

name

llm-context

description

USE FOR RAG/LLM grounding. Returns pre-extracted web content (text, tables, code) optimized for LLMs. GET + POST. Adjust max\_tokens/count based on complexity. Supports Goggles, local/POI. For AI answers use answers. Recommended for anyone building AI/agentic applications.

> **Requires API Key**: Get one at [https://api.search.brave.com](https://api.search.brave.com/)
> 
> **Plan**: Included in the **Search** plan. See [https://api-dashboard.search.brave.com/app/subscriptions/subscribe](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

Feature

LLM Context (this)

AI Grounding (`answers`)

Output

Raw extracted content for YOUR LLM

End-to-end AI answers with citations

Interface

REST API (GET/POST)

OpenAI-compatible `/chat/completions`

Searches

Single search per request

Multi-search (iterative research)

Speed

Fast (<1s)

Slower

Plan

Search

Answers

Endpoint

`/res/v1/llm/context`

`/res/v1/chat/completions`

Best for

AI agents, RAG pipelines, tool calls

Chat interfaces, research mode

## 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)

`spellcheck`

bool

No

`true`

Whether to spellcheck the query before searching

`freshness`

string

No

`""`

Filters search results by page age. The age of a page is determined by the most relevant date reported by the content, such as its published or last modified date. Supported values: `pd` (24h or less), `pw` (7 days or less), `pm` (31 days or less), `py` (365 days or less), or a custom date range `YYYY-MM-DDtoYYYY-MM-DD` (e.g. `2022-04-01to2022-07-30`).

### 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-256)

`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

Parameter

Type

Required

Default

Description

`context_threshold_mode`

string

No

`null`

Relevance threshold for including content (`strict`/`balanced`/`lenient`/`disabled`)

`safesearch`

string

No

`null`

Adult content filter (`off`/`moderate`/`strict`); not set means no filtering, except local recall which stays `strict`

`enable_local`

bool

No

`null`

Local recall control (`true`/`false`/`null`, see below)

`goggles`

string/list

No

`null`

Goggle URL or inline definition for custom re-ranking

`enable_source_metadata`

bool

No

`false`

Adds `site_name`, `favicon`, `thumbnail` and `description` to each `sources[url]` entry

## 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

Mode

Behavior

`null` (not set)

**Default** — resolves to `lenient` on the current API version

`strict`

Higher threshold — fewer but more relevant results

`balanced`

Good balance between coverage and relevance

`lenient`

Lower threshold — more results, may include less relevant content

`disabled`

No threshold filtering — return all extracted content

## Local Recall

The `enable_local` parameter controls location-aware recall:

Value

Behavior

`null` (not set)

**Auto-detect** — local recall enabled when any location header is provided

`true`

**Force local** — always use local recall, even without location headers

`false`

**Force standard** — always use standard web ranking, even with location headers

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

## Location Headers

Header

Type

Description

`X-Loc-Lat`

float

Latitude (-90.0 to 90.0)

`X-Loc-Long`

float

Longitude (-180.0 to 180.0)

`X-Loc-City`

string

City name

`X-Loc-State`

string

State/region code (ISO 3166-2)

`X-Loc-State-Name`

string

State/region name

`X-Loc-Country`

string

2-letter country code

`X-Loc-Postal-Code`

string

Postal code

> **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.

Use Case

Goggle Rules

Official docs only

`$discard\n$site=docs.python.org`

Exclude user content

`$discard,site=reddit.com\n$discard,site=stackoverflow.com`

Academic sources

`$discard\n$site=arxiv.org\n$site=scholar.google.com`

No paywalls

`$discard,site=medium.com`

Method

Example

**Hosted**

`--data-urlencode "goggles=https://raw.githubusercontent.com/brave/goggles-quickstart/main/goggles/1k_short.goggle"`

**Inline**

`--data-urlencode 'goggles=$discard\n$site=example.com'`

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

**Syntax**: Rules start with `$` + comma-separated options. **Actions** (pick one): `discard`, `boost[=N]`, `downrank[=N]` — N is an integer 1–10. **Site filter**: `site=DOMAIN`. Example: `$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](https://search.brave.com/goggles/discover) · [Syntax](https://search.brave.com/help/goggles) · [Quickstart](https://github.com/brave/goggles-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", "2025-01-15T13:45:02Z"\]
    }
  }
}

### 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": \[\]
    }
  }
}

### Response Fields

Field

Type

Description

`grounding`

object

Container for all grounding content by type

`grounding.generic`

array

Array of URL objects with extracted content (main grounding data)

`grounding.generic[].url`

string

Source URL

`grounding.generic[].title`

string

Page title

`grounding.generic[].snippets`

array

Extracted smart chunks relevant to the query

`grounding.poi`

object/null

Point of interest data (only with local recall)

`grounding.poi.name`

string/null

Point of interest name

`grounding.poi.url`

string/null

POI source URL

`grounding.poi.title`

string/null

POI page title

`grounding.poi.snippets`

array/null

POI text snippets

`grounding.map`

array

Map/place results (only with local recall)

`grounding.map[].name`

string/null

Place name

`grounding.map[].url`

string/null

Place source URL

`grounding.map[].title`

string/null

Place page title

`grounding.map[].snippets`

array/null

Place text snippets

`sources`

object

Metadata for all referenced URLs, keyed by URL

`sources[url].title`

string

Page title

`sources[url].hostname`

string

Source hostname

`sources[url].age`

array

The page's date in four fixed positions: full date, `YYYY-MM-DD`, relative age, ISO 8601 timestamp. Empty when the page has no known date

`sources[url].description`

string

The page's own description, independent of the query. Requires `enable_source_metadata`

`sources[url].site_name`

string

Site name. Requires `enable_source_metadata`

`sources[url].favicon`

string

Favicon URL. Requires `enable_source_metadata`

`sources[url].thumbnail`

object/null

Page thumbnail (`src`, `original`). Requires `enable_source_metadata`

`sources[url].snippet`

string?

Best snippet for the page

**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.