Search

POST /v1/search searches the web and returns the top results: their title, URL, a snippet, and the page’s date and site name when they are known. With fetch, the top pages come back as Markdown too, in the same request, so an agent can read them straight away. No session is needed.

Search

curl -X POST https://api.boxline.dev/v1/search \  -H "x-api-key: $BOXLINE_API_KEY" \  -H "content-type: application/json" \  -d '{"query": "playwright connect over cdp", "limit": 5}'

import { Boxline } from "@boxline/sdk";const bx = new Boxline(); // reads BOXLINE_API_KEY and BOXLINE_API_URLconst { results, cached } = await bx.search({ query: "playwright connect over cdp", limit: 5 });for (const r of results) console.log(r.title, r.url, r.publishedAt ?? "");console.log("from the cache:", cached);

from boxline import Boxlinebx = Boxline()  # reads BOXLINE_API_KEY and BOXLINE_API_URLfound = bx.search("playwright connect over cdp", limit=5)for r in found["results"]:    print(r["title"], r["url"], r.get("publishedAt", ""))print("from the cache:", found["cached"])

{  "query": "playwright connect over cdp",  "cached": false,  "ms": 412,  "results": [    {      "title": "BrowserType | Playwright",      "url": "https://playwright.dev/docs/api/class-browsertype",      "snippet": "A CDP websocket endpoint or http url to connect to.",      "siteName": "Playwright"    },    {      "title": "Connecting Playwright to an Existing Browser | BrowserStack",      "url": "https://www.browserstack.com/guide/playwright-connect-to-existing-browser",      "snippet": "Playwright can connect directly to an existing Chromium instance via CDP.",      "publishedAt": "2025-12-23T09:55:22.000Z",      "siteName": "BrowserStack"    }  ]}

Each result has title, url (http or https) and snippet (plain text), and publishedAt (ISO 8601) and siteName when they are known. ms is the time of the whole request, fetched pages included.

Options

Every country and language code that works is listed in the API reference.

Read the top pages

With fetch, the top results are also opened like Fetch does: in a real browser inside a sandbox, never by the API itself. Each of those results then has:

• content: the page as Markdown (links and images absolute, no heading permalinks), or null when it could not be loaded;
• page: { finalUrl, status, title, captcha, ms }, or null when it failed;
• error: { code, message } when it failed (page_unreachable, page_timeout, not_a_web_page for a PDF, no_capacity, …), else null.

curl -X POST https://api.boxline.dev/v1/search \  -H "x-api-key: $BOXLINE_API_KEY" \  -H "content-type: application/json" \  -d '{"query": "playwright connect over cdp", "limit": 5, "fetch": 2}'

import { Boxline } from "@boxline/sdk";const bx = new Boxline(); // reads BOXLINE_API_KEY and BOXLINE_API_URLconst found = await bx.search({ query: "playwright connect over cdp", limit: 5, fetch: 2 });for (const r of found.results.slice(0, 2)) {  console.log(r.url, r.error ? `could not load: ${r.error.code}` : r.content?.slice(0, 200));}

from boxline import Boxlinebx = Boxline()  # reads BOXLINE_API_KEY and BOXLINE_API_URLfound = bx.search("playwright connect over cdp", limit=5, fetch=2)for r in found["results"][:2]:    print(r["url"], f"could not load: {r['error']['code']}" if r.get("error") else (r.get("content") or "")[:200])

One page failing never fails the search. Fetching needs your plan’s quick APIs, and each page counts against the fetch, screenshot and PDF rate limit. A proxy applies to those pages only; without fetch it is a 400.

Cache and allowance

• The same search (the same words and options) by your project within an hour is answered from memory, with cached: true. It is not sent to the search provider and not counted. Each API server keeps its own cache, and fetched pages are always opened fresh.
• Every other search counts. Your plan includes searchesPerMonth searches per calendar month (UTC), for all the projects of your organization together. Beyond that, each 1,000 costs extraSearchesPer1000Usd. On a plan without extra searches (Free), the next search is 402 plan_limit until the 1st.
• The starting allowances are 100 searches a month on Free, 1,000 on Hobby, 10,000 on Startup and 100,000 on Scale, then $5 per 1,000 on the paid plans. GET /v1/pricing has the current numbers in webSearch.byPlan, and GET /v1/project/usage shows searches: { count, costUsd }. See Pricing.
• Your plan needs web search (webSearch; 402 feature_not_in_plan without it). Every plan has it today.

Errors

Privacy

The platform keeps each search’s query text for 30 days, for billing questions and abuse reports. After that it keeps only that a search happened, for 400 days, for invoices.

In the agent and the MCP server

• AI agent runs have a web_search tool: titles, URLs, snippets and dates, then the agent opens a result in the browser. Each call is a search like POST /v1/search, with the same cache, allowance and billing. See What the agent can do.
• The MCP server has a web_search tool.