> ## Documentation Index
> Fetch the complete documentation index at: https://docs.andiai.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Response format
> Structure of the Andi AI Search API response, including result types, metrics, and the context format for LLMs.
The API returns JSON by default. The `format=context` option returns markdown with YAML frontmatter instead — see [context format](#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 | Generated answer for the query (may be empty) |
| `type` | string | Yes | Same as `results_type` |
| `title` | string | Yes | Title summarizing the search results |
| `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 |
### Type-specific arrays
Depending on the query intent, the response may include additional arrays alongside `results`:
| Field | Present when |
| ---------- | ------------------------- |
| `videos` | Video intent queries |
| `images` | Image intent queries |
| `news` | News intent queries |
| `places` | Location/business queries |
| `profiles` | People-related queries |
| `social` | Social media queries |
| `academic` | Scholarly queries |
## 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 | Domain name |
| `date` | string | No | Publication date |
| `snippet` | string | No | Query-relevant text excerpt (distinct from `desc`) |
| `answer` | string | No | Inline answer for instant answer results |
| `extracts` | array | No | Text extracts from the page (when `extracts=true`) |
### 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](#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 |
| `bang` | string | Bang shortcut for the result domain |
### Accessing key fields
```python theme={null}
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:
```json theme={null}
{
"results_type": "Weather",
"answer": "",
"type": "Weather",
"title": "Weather in San Francisco",
"results": [],
"weather": {
"location": {
"name": "San Francisco",
"country": "US",
"coordinates": {
"latitude": 37.7749,
"longitude": -122.4194
}
},
"temperature": 62,
"feelsLike": 59,
"units": "imperial",
"description": "Partly Cloudy",
"humidity": 72,
"windSpeed": 12,
"windDirection": 270,
"pressure": 1013,
"icon": "partly-cloudy",
"cloudiness": 40,
"visibility": 10000,
"timestamp": "2025-03-15T14:00:00Z"
},
"metrics": {
"query": "weather san francisco",
"intent": "WeatherIntent",
"timestamp": "2025-03-15T14:00:01Z",
"duration": 850,
"cost_dollars": 0.0018,
"queries_executed": 1,
"api_requests_count": 2,
"results_returned": 0,
"total_results_found": 0
}
}
```
Use the `units` parameter to get results in `metric` or `imperial`. The default is auto-detected from the `country` parameter.
### Calculation
Mathematical queries return a `calculation` object:
```json theme={null}
{
"results_type": "Calculator",
"answer": "",
"type": "Calculator",
"title": "150 * 1.08",
"results": [],
"calculation": {
"expression": "150 * 1.08",
"result": "162"
},
"metrics": { "..." : "..." }
}
```
Image queries return an `images` array with thumbnail and dimension data:
```json theme={null}
{
"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.com",
"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** but may be empty for instant answers (weather, calculations)
* **`desc` vs `snippet`**: `desc` is the page's general description; `snippet` is a query-relevant excerpt (when available)
* **`answer` at top level** is a generated answer string (may be empty); `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](/features/query-parameters#intent-values) for the full list of intent aliases.
## Metrics
The response always includes a `metrics` object with performance and billing data:
```json theme={null}
{
"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 |
| `cost_dollars` | number | Amount charged for this request in USD |
| `effort` | string | Resolved effort tier (`low`/`medium`/`high`/`max`). Present when `effort` was set, or when `searchMode` pins a fixed mode. |
| `queries_executed` | integer | Number of queries executed |
| `api_requests_count` | integer | Number of API requests made |
| `results_returned` | integer | Results returned in this response |
| `total_results_found` | integer | Total results found across sources |
| `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.
```bash theme={null}
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:
```yaml theme={null}
---
format: "andi-context/v1"
query: "climate change effects"
results_count: 10
timestamp: "2026-07-14T21:30:00Z"
search_mode: "auto"
cost_dollars: 0.0043
cached: false
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`), when `effort` was set or `search_mode` pins a fixed mode. |
| `cost_dollars` | When available | Amount charged in USD |
| `cached` | When available | Whether response was from cache |
| `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 `` block with its own frontmatter:
```text theme={null}
---
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...
Rising temperatures have shifted planting windows by 2-3 weeks in temperate
zones over the past decade.
```
A `source` line appears in the frontmatter only when the display source differs from the domain in the `` tag. 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](#type-specific-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:
```text theme={null}
## News results
- 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..."
```
Items already present in the main `` 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
Full parameter reference.
Fetch full page content from any URL.
Use search results as LLM context.
MCP server and agent integration.