Response format

The API returns JSON by default. The format=context option returns markdown with YAML frontmatter instead — see context format below.

The results_type field tells you the shape of the response. Use it to determine which arrays and objects are present — for example, results_type: "Weather" means a weather object is included.

Top-level fields

Field	Type	Always present	Description
`results_type`	string	Yes	Category of results (e.g., `Search`, `News`, `Weather`, `Entity`, `Calculator`)
`answer`	string	Yes	Instant answer for the query when one is found — for example a definition, a weather line or a calculation — otherwise an empty string. On news feeds, a short summary of the headlines when available.
`type`	string	Yes	Same as `results_type`
`title`	string	Yes	Your query text (for a news feed, the feed’s description)
`results`	array	Yes	Search results
`metrics`	object	Yes	Search performance and cost metrics
`safeSearch`	object	No	Echo of safe-search state: `{requested, applied}`. Present on cache misses. Use this to confirm your `safe` parameter was honored.
`correctedQuery`	string	No	Spell-corrected query, when a correction was detected. Deep and exhaustive modes also re-run the search with the corrected query.
`related_searches`	array	No	Related search suggestions
`topics`	array	No	Related topics
`related_topics`	array	No	Related topic names for entity answers
`infobox`	object	No	Facts panel for an entity answer: `heading`, `source` and `items` (`label`/`value` pairs)
`disambiguation`	object	No	Possible meanings when the query is ambiguous: `message` and `options` (each with `title`, `text` and `url`)
`aiSummary`	object	No	News feeds only: the pre-written news summary — `text`, `generatedAt`, `model` (a short label) and `mode` (`pregen`, written ahead of your request). The same text is in `answer`.

Type-specific arrays

When the search finds items of these kinds, the response adds them as extra arrays alongside results — for any query, not only queries with a matching intent.

Field	Contains
`videos`	Video results
`images`	Image results
`news`	News articles
`places`	Places and businesses
`profiles`	People and entity profiles
`social`	Social posts
`academic`	Scholarly papers

Search results

Each result in the results array has this structure:

Field	Type	Always present	Description
`title`	string	Yes	Page title
`link`	string	Yes	Page URL (returned as `url` when `linkFormat=url`)
`desc`	string	Yes	Page description or summary
`source`	string	Yes	Site or publisher name (for example `Wikipedia`); a name derived from the domain when none is known.
`date`	string	No	Publication date
`dateModified`	string	No	When the page was last updated, if known
`snippet`	string	No	Query-relevant text excerpt (distinct from `desc`)
`answer`	string	No	Inline answer for instant answer results
`extracts`	array	No	Query-relevant passages from the page. Returned with `extracts=true`, and by default with `format=context` and `metadata=full`.
`queryIndices`	array	No	Multi-query only: which of your queries (0-based) found this result

Fields added by `metadata=full`

These fields appear on results when you pass metadata=full. They are not included in the default metadata=basic response.

Field	Type	Description
`type`	string	Result type when classified (see result types)
`image`	string	Preview image URL
`contentType`	string	Schema.org content type (e.g., `Article`, `NewsArticle`)
`contentSafety`	object	Safety classification: `{rating, safeSearchApplied}` where `rating` is `"safe"`, `"unsafe"`, or `"unknown"`
`reader`	object	Extracted page content and metadata. With `content=true`, the full page text is here at any metadata level, in `reader.markdown` (or `reader.content` when the page has no markdown version).
`bang`	string	Bang shortcut for the result domain

Accessing key fields

data = response.json()

for result in data["results"]:
    # Always present
    print(result["title"], result["link"], result["source"])

    # Optional fields — check before accessing
    if result.get("snippet"):
        print(f"Snippet: {result['snippet']}")
    if result.get("extracts"):
        print(f"Extract: {result['extracts'][0][:200]}")
    if result.get("date"):
        print(f"Published: {result['date']}")

Result types

The type field indicates the kind of result:

Type	Description
`website`	Standard web page
`blog`	Blog post
`news`	News article
`video`	Video content
`image`	Image content
`place`	Business or place
`profile`	Person or entity profile
`social`	Social media content
`academic`	Scholarly or research content
`calculation`	Math computation result
`weather`	Weather data
`computation`	Computed answer
`instant answer`	Direct answer to a factual query

Instant answers

Some queries trigger instant answers alongside regular results.

Weather

Queries about weather return a weather object:

{
  "results_type": "Weather",
  "answer": "60°F in San Francisco, US. Feels like 59°F. clear sky. Humidity: 76%. Wind: 22 mph.",
  "type": "Weather",
  "title": "weather in san francisco",
  "results": ["..."],
  "weather": {
    "location": {
      "name": "San Francisco",
      "country": "US",
      "coordinates": {
        "latitude": 37.7749,
        "longitude": -122.4194
      }
    },
    "temperature": 59.95,
    "feelsLike": 59.22,
    "units": "imperial",
    "description": "clear sky",
    "humidity": 76,
    "windSpeed": 21.85,
    "windDirection": 280,
    "pressure": 1010,
    "icon": "01d",
    "cloudiness": 0,
    "visibility": 10000,
    "timestamp": 1790646026000
  },
  "metrics": {
    "query": "weather in san francisco",
    "intent": "WeatherIntent",
    "timestamp": "2026-09-29T01:43:39.185Z",
    "duration": 1478,
    "response_time_ms": 1478,
    "queries_executed": 1,
    "api_requests_count": 1,
    "results_returned": 10,
    "total_results_found": 89559425,
    "effort": "low",
    "cost_dollars": 0.014869
  }
}

Use the units parameter to get results in metric or imperial. The default is auto-detected from the country parameter. weather.timestamp is the time of the reading in Unix epoch milliseconds. The answer line and the regular web results come back alongside the weather object.

Calculation

Mathematical queries return a calculation object:

{
  "results_type": "Calculator",
  "answer": "150 * 1.08 = 162",
  "type": "Calculator",
  "title": "150 * 1.08",
  "results": ["..."],
  "calculation": {
    "expression": "150 * 1.08",
    "result": "162",
    "rawResult": 162
  },
  "metrics": { "..." : "..." }
}

Image results

Image queries return an images array with thumbnail and dimension data:

{
  "results_type": "Search",
  "answer": "",
  "type": "Search",
  "title": "Mountain landscape images",
  "results": [],
  "images": [
    {
      "title": "Mountain landscape",
      "link": "https://example.com/photo",
      "image": "https://example.com/photo.jpg",
      "source": "Example Photos",
      "type": "image",
      "thumbnail": "https://example.com/photo_thumb.jpg",
      "width": "1920",
      "height": "1080"
    }
  ],
  "metrics": { "..." : "..." }
}

Image results include thumbnail (thumbnail URL), width, and height as string values.

Parsing tips

Check results_type first to know the response shape before accessing type-specific fields
results is always an array. Instant answers (weather, calculations) come with regular web results as well
desc vs snippet: desc is the page’s general description; snippet is a query-relevant excerpt (when available)
answer at top level is the instant answer text when one is found (otherwise an empty string); answer on individual results is an inline answer for instant answer result types
Optional fields (date, image, snippet, extracts) may not be present on every result — always check before accessing

Search intents

The results_type and type fields reflect what kind of search was performed. You can force an intent with the intent parameter, or let the API auto-detect it. Common intent aliases:

Alias	Intent	Extra fields
`search`	General web search	—
`news`	News articles	`news`
`video`	Video content	`videos`
`images`	Image search	`images`
`weather`	Weather queries	`weather`
`calculate`	Math expressions	`calculation`
`wiki`	Wikipedia/knowledge	—
`code`	Programming queries	—
`recipe`	Recipe search	—
`place`	Business search	`places`
`time`	Time queries	—

See query parameters for the full list of intent aliases.

Metrics

The response always includes a metrics object with performance and billing data:

{
  "results": ["..."],
  "metrics": {
    "query": "quantum computing",
    "intent": "InstantAnswerIntent",
    "timestamp": "2026-07-15T01:29:20.468Z",
    "duration": 1713,
    "queries_executed": 1,
    "api_requests_count": 1,
    "results_returned": 3,
    "total_results_found": 71800116,
    "cost_dollars": 0.029886
  }
}

Field	Type	Description
`query`	string	The query as processed
`intent`	string	Detected or forced search intent
`timestamp`	string	Timestamp of the request
`duration`	number	Total request time in milliseconds
`response_time_ms`	integer	Same as `duration`
`cost_dollars`	number	Amount charged for this request in USD
`effort`	string	Resolved effort tier (`low`/`medium`/`high`/`max`): the tier `auto` chose, or the one you pinned with `searchMode` or `effort`.
`queries_executed`	integer	Number of queries executed
`api_requests_count`	integer	Number of queries in your request (the same as `queries_executed`)
`results_returned`	integer	Results returned in this response
`total_results_found`	integer	Rough estimate of matching pages, as reported by sources (0 for news feeds)
`queries_provided`	integer	Number of queries you sent. Only present when more than 5 were sent.
`queries_truncated`	integer	How many queries were dropped because only the first 5 run. Only present when more than 5 were sent.
`cached`	boolean	Whether this response was served from cache. Only present on cache hits.
`cache_age_seconds`	integer	How old the cached response is, in seconds. Only present on cache hits.

Context format

With format=context, the API returns results as markdown with YAML frontmatter instead of JSON. This format is sized for LLM context windows and can be passed directly to a language model without JSON parsing.

curl "https://api.andiai.com/api/v1/search?q=climate+change+effects&format=context" \
  -H "x-api-key: YOUR_API_KEY"

Document-level frontmatter

The response starts with a YAML frontmatter block describing the search:

---
format: "andi-context/v1"
query: "climate change effects"
results_count: 10
timestamp: "2026-07-14T21:30:00Z"
search_mode: "auto"
cost_dollars: 0.0043
response_time_ms: 1240
---

Field	Always present	Description
`format`	Yes	Always `"andi-context/v1"`
`query`	Yes	The search query
`results_count`	Yes	Number of results
`timestamp`	Yes	Request timestamp
`intent`	When available	Detected search intent
`results_type`	When available	Type of results
`corrected_query`	When available	Spell-corrected query
`related_searches`	When available	Related search suggestions
`topics`	When available	Related topics
`search_mode`	When available	The mode this request ran with. With the default `auto`, this shows the mode Andi selected for the query.
`effort`	When available	Resolved effort tier (`low`/`medium`/`high`/`max`): the tier `auto` chose, or the one you pinned with `searchMode` or `effort`.
`cost_dollars`	When available	Amount charged in USD
`cached`	When available	`true` when the response came from cache; omitted otherwise
`cache_age_seconds`	When available	Cache age in seconds
`response_time_ms`	When available	Response time (omitted on cache hits)

Per-result structure

Each result renders as an <article> block with its own frontmatter:

<article source="example.com" rank="1">
---
title: "Climate Change Effects on Global Agriculture"
url: https://example.com/climate-agriculture
date: 2026-06-10
author: Dr. Sarah Chen
---

Climate change is altering growing seasons and precipitation patterns across
major agricultural regions...

<extracts>
> Rising temperatures have shifted planting windows by 2-3 weeks in temperate zones over the past decade.
</extracts>
</article>

A source line appears in the frontmatter only when the display source differs from the domain in the <article> tag. A date_modified line appears when the page’s last-updated date is known. With metadata=full, each article’s frontmatter adds domain, publisher, type, content_type, lang, word_count, image, keywords, and summary when available.

Type-specific sections

The same type-specific groups the JSON response carries as additional arrays render as trailing sections after the main results, so a context-format caller sees everything a JSON caller would. Sections appear only when the group has results, in this order: Academic results, News results, Video results, Social results, Place results, Profile results. (images is JSON-only.) Each section is a markdown heading followed by a compact item list — title, url, and when available date, source, description, and duration for videos:

## News results

<news count="2">
- title: "Heat Records Fall Across Southern Europe"
  url: "https://example.com/heat-records"
  date: "2026-07-12"
  source: "example.com"
  desc: "Temperatures exceeded seasonal norms for a third consecutive week..."
</news>

Items already present in the main <article> results are not repeated in these sections.

Extracts in context format

extracts defaults to on for format=context (the opposite of JSON, where it defaults to off). To disable extracts in context format, pass extracts=false.

Next steps

Query parameters

Full parameter reference.

Content retrieval

Fetch full page content from any URL.

RAG pipeline

Use search results as LLM context.

Build with AI agents

MCP server and agent integration.

Getting started

Search

Features

Resources

Top-level fields

Type-specific arrays

Search results

Fields added by `metadata=full`

Accessing key fields

Result types

Instant answers

Weather

Calculation

Parsing tips

Search intents

Metrics

Context format

Document-level frontmatter

Per-result structure

Type-specific sections

Extracts in context format

Next steps

Query parameters

Content retrieval

RAG pipeline

Build with AI agents

​Top-level fields

​Type-specific arrays

​Search results

​Fields added by metadata=full

​Accessing key fields

​Result types

​Instant answers

​Weather

​Calculation

​Parsing tips

​Search intents

​Metrics

​Context format

​Document-level frontmatter

​Per-result structure

​Type-specific sections

​Extracts in context format

​Next steps

Query parameters

Content retrieval

RAG pipeline

Build with AI agents

Top-level fields

Type-specific arrays

Search results

Fields added by `metadata=full`

Accessing key fields

Result types

Instant answers

Weather

Calculation

Parsing tips

Search intents

Metrics

Context format

Document-level frontmatter

Per-result structure

Type-specific sections

Extracts in context format

Next steps