> ## Documentation Index
> Fetch the complete documentation index at: https://docs.keenable.ai/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Every page is listed in https://docs.keenable.ai/llms.txt. To pick a product for a job, read https://docs.keenable.ai/choose.md
> Setup steps for agents, covering the SDKs, the MCP server and the CLI: https://docs.keenable.ai/skill.md
> Keenable search and fetch work without an API key. To add them to code, use the official SDK for the project's language: https://docs.keenable.ai/sdks.md
> Without a key, call POST https://api.keenable.ai/v1/search/public or GET https://api.keenable.ai/v1/fetch/public with an X-Keenable-Title header that names your app.
> With a key, send it in the X-API-Key header and read it from the KEENABLE_API_KEY environment variable. Never ask a user to paste a key into chat. Every access method: https://docs.keenable.ai/auth.md
> To get an API key without the console, use device login: https://docs.keenable.ai/authentication.md#device-login
> MCP server: https://api.keenable.ai/mcp (no key, or X-API-Key; keyless Codex uses https://api.keenable.ai/mcp-public), or https://api.keenable.ai/mcp-oauth for OAuth sign-in. These docs are an MCP server at https://docs.keenable.ai/mcp and the OpenAPI spec is at https://docs.keenable.ai/api-reference/openapi.json
> Keenable searches and fetches public web pages. If a question needs no web information, skip the call.
> On 402 with an API key (code insufficient_credits), stop and ask a human to add credits; don't retry. On 429, wait the number of seconds in Retry-After, then retry. Before you ship, follow https://docs.keenable.ai/production.md
> Every error, with its cause and fix, is in https://docs.keenable.ai/errors.md and moving from another search API is covered in https://docs.keenable.ai/migrate.md
> Before you compare Keenable with another search API, read https://docs.keenable.ai/guides/evaluate-search-apis.md

# Enrich a list with web data in one SELECT query

> Add web facts to every item in a list with one SELECT query: one search per item, fields extracted by an LLM, one row per item with its source count.

Add the same facts to every item in a list, such as a license and a first release year for each database, with one query instead of one script per item. [SELECT](https://docs.keenable.ai/select.md) runs one search per item, extracts the fields you name from each page with an LLM, and groups the pages back into one row per item.

## Recipe prompt

Paste this into your coding agent. It works in any agent that has the Keenable SELECT MCP server connected:

```text Recipe prompt theme={"theme":{"light":"github-light-high-contrast","dark":"dark-plus"}}
Read https://docs.keenable.ai/recipes/enrich-a-list-with-select.md. Then use the Keenable SELECT select tool to enrich this list: <paste your list>. Write one WEB_SEARCH query per item in the form '<item> <what I want to know>', extract each field I name with SEM_EXTRACT, group by the item taken from the query column, and keep COUNT(DISTINCT url) AS sources. Show me the table, then name any row where sources is 1 so I can check it.
```

To connect the server, see [SELECT → Connect](https://docs.keenable.ai/select.md#connect).

## What you build

The query has two layers. The inner `SELECT` makes one row per page. The outer one groups those rows into one row per item:

| Part | In the query | What it does |
| - | - | - |
| One search per item | `WEB_SEARCH('PostgreSQL database license and first release year', …)` | Runs every search and merges the pages into one row per URL |
| Item key | `regexp_extract(query, '^(.*) database', 1)` | Reads the item's name back from the `query` column, the search that found the page |
| Fields | `SEM_EXTRACT(content, 'name of the software license …')` | One value per page, or `NULL` if the page doesn't state it |
| One row per item | `GROUP BY item` with `MODE(...)` | Keeps the value most pages agree on |
| Confidence | `COUNT(DISTINCT url) AS sources` | How many pages the row is built from |

This is the query the sample sends:

```sql theme={"theme":{"light":"github-light-high-contrast","dark":"dark-plus"}}
SELECT
  item,
  MODE(license) AS license,
  MODE(first_release) AS first_release,
  COUNT(DISTINCT url) AS sources
FROM (
  SELECT
    regexp_extract(query, '^(.*) database', 1) AS item,
    url,
    SEM_EXTRACT(content, 'name of the software license the project is released under') AS license,
    SEM_EXTRACT(content, 'year of the first public release, number only') AS first_release
  FROM WEB_SEARCH(
    'PostgreSQL database license and first release year',
    'SQLite database license and first release year',
    'DuckDB database license and first release year'
  )
)
GROUP BY item
ORDER BY item
```

A query must read `FROM` a `WEB_SEARCH(...)` call, a `WEB_FETCH(...)` call or a result set ID, so the list goes into the searches themselves. If the list came from an earlier query, read its result set ID and run `WEB_SEARCH(item || ' license and first release year')` for each row instead. See [Recipes in the function reference](https://docs.keenable.ai/select.md#recipes).

## When it runs

On demand, once per list. The query takes seconds to minutes, because it runs real searches, fetches pages and calls an LLM for each page. Every call stores its table as a result set for 30 days, so follow-up questions about the same rows run without new searches.

## Code

Your agent runs the query for you over MCP. To run it from your own code, the TypeScript tab calls the `select` tool on `https://select.keenable.ai/mcp` with your API key, through the official MCP TypeScript SDK. The curl tab sends the same query to the pay-per-request path, which needs no account:

```typescript TypeScript theme={"theme":{"light":"github-light-high-contrast","dark":"dark-plus"}}
// npm install @modelcontextprotocol/sdk
import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";

const items = ["PostgreSQL", "SQLite", "DuckDB"];

// One search per item; the query column tells you which item a page came from.
// Doubling each ' keeps an item like "Hadoop's" inside its SQL string.
const sql = (s: string) => `'${s.replaceAll("'", "''")}'`;
const searches = items.map((item) => sql(`${item} database license and first release year`)).join(",\n    ");
const query = `
SELECT
  item,
  MODE(license) AS license,
  MODE(first_release) AS first_release,
  COUNT(DISTINCT url) AS sources
FROM (
  SELECT
    regexp_extract(query, '^(.*) database', 1) AS item,
    url,
    SEM_EXTRACT(content, 'name of the software license the project is released under') AS license,
    SEM_EXTRACT(content, 'year of the first public release, number only') AS first_release
  FROM WEB_SEARCH(
    ${searches}
  )
)
GROUP BY item
ORDER BY item`;

async function main() {
  const transport = new StreamableHTTPClientTransport(new URL("https://select.keenable.ai/mcp"), {
    requestInit: { headers: { "X-API-Key": process.env.KEENABLE_API_KEY ?? "" } },
  });
  const client = new Client({ name: "enrich-a-list", version: "1.0.0" });
  await client.connect(transport);

  // A query takes seconds to minutes: raise the request timeout from its default
  const result = await client.callTool({ name: "select", arguments: { query } }, undefined, { timeout: 600_000 });
  for (const part of result.content as Array<{ type: string; text?: string }>) {
    if (part.type === "text") console.log(part.text);
  }
  await client.close();
}

main();
```

```bash curl theme={"theme":{"light":"github-light-high-contrast","dark":"dark-plus"}}
# No account: send the same query to the x402 path. The first call returns the 402 offer.
curl -i -X POST "https://api.keenable.ai/v1/x402/select" \
  -H "Content-Type: application/json" \
  -d @- <<'JSON'
{ "query": "SELECT item, MODE(license) AS license, MODE(first_release) AS first_release, COUNT(DISTINCT url) AS sources FROM (SELECT regexp_extract(query, '^(.*) database', 1) AS item, url, SEM_EXTRACT(content, 'name of the software license the project is released under') AS license, SEM_EXTRACT(content, 'year of the first public release, number only') AS first_release FROM WEB_SEARCH('PostgreSQL database license and first release year', 'SQLite database license and first release year', 'DuckDB database license and first release year')) GROUP BY item ORDER BY item" }
JSON
```

The TypeScript sample builds the `WEB_SEARCH` list from the `items` array and prints the tool's text output. The curl call returns the `402` offer: pay it as in [SELECT over x402](https://docs.keenable.ai/pay-per-request.md#select-over-x402), and the paid retry returns the table.

## Example output

The result is a table with one row per item and four columns: `item`, `license`, `first_release` and `sources`. A run returns rows like these. This table is illustrative: values and `sources` counts change with what the searches find on the day.

| item | license | first\_release | sources |
| - | - | - | - |
| DuckDB | MIT License | 2019 | 4 |
| PostgreSQL | PostgreSQL License | 1996 | 6 |
| SQLite | Public domain | 2000 | 5 |
| A table larger than about 50,000 characters comes back as a few sample rows, and the full table stays available through the result set ID. Over x402, the JSON response carries `result_set_id`, `total_rows`, `columns` and either `rows` or `preview`. | | | |

## Production notes

| Situation | What happens | What to do |
| - | - | - |
| `401` | No credential reached the server, or it's invalid. | Check the `X-API-Key` header and the key. |
| `429` | Too many queries are running at once, on your account or across the service. | Retry shortly. Run lists one query at a time. |
| A query that can't run, over x402 | `400` for an invalid query, `429` for too many running queries, `502` with `select_failed` when the service couldn't run it. None of them is charged. | Read the error, fix the query, and check `retryable` on a `502`. |
| A value with `sources` of 1 | Only one page stated it. | Check that page. Extraction doesn't fact-check its sources. |
| Two item searches find the same page | `WEB_SEARCH` keeps one row per URL with one `query` value, so the page counts toward only one item. | Expect a lower `sources` on items that share pages, such as a comparison article. |
| A client gives up on a slow call | The query is cancelled. | Raise your client's request timeout, as the TypeScript sample does. |
| A query selects the whole `content` column | The server rejects it. | Extract fields from `content`, or take a bounded part such as `substr(content, 1, 10000)`. |

Over x402, a query costs \$0.10 when it succeeds. See [Pay per request](https://docs.keenable.ai/pay-per-request.md#select-over-x402).

## Next steps

* [SELECT](https://docs.keenable.ai/select.md): connect a client, every function and result sets.
* [Agent pays with x402](https://docs.keenable.ai/recipes/agent-pays-with-x402.md): pay per request from a wallet, with a price cap.
* [SELECT guide](https://select.keenable.ai/guide.md): the full dialect guide your agent reads.
* [Recipes](https://docs.keenable.ai/recipes.md): every recipe on one page.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.