POST /v1/search
Search
Returns ranked candidate URLs, snippets, dates, related_searches, and credits_used.
searchFind the public pages worth retrieving
Use ByteKit Search to return ranked public results, snippets, dates, and related queries. Then your app sends selected URLs to Scrape, Schema, Bulk, or Monitors when you need the page behind the result.
REQUEST POST /v1/search
curl -X POST https://api.bytekit.com/v1/search \ -H "Authorization: Bearer sk_live_..." \ -H "Content-Type: application/json" \ -d '{ "query": "wireless headphones review", "type": "web", "limit": 10 }'
EXAMPLE RESPONSE 200 OK
{
"id": "sr_9f2a71c4",
"query": "wireless headphones review",
"results": [
{
"position": 1,
"title": "Best wireless headphones 2026",
"url": "https://example.com/best-headphones",
"snippet": "Our picks after 40 hours…"
}
],
"related_searches": ["noise cancelling headphones"],
"credits_used": 1
} Example response · not a full schema. Search returns candidate URLs — your app chooses what to retrieve.
workflowSearch → choose result → Scrape / Schema / Bulk / Monitors
Search gives your workflow candidate sources. ByteKit does not decide what to trust, retrieve, or monitor. Your application does.
1
2
your app
Choose result
Your application decides which candidate URLs to trust and retrieve. ByteKit does not choose for you.
3
POST /v1/scrape
Scrape or Schema
Pass a chosen URL to Scrape for page content, or to Schema to extract known fields.
4
/bulk · /monitors
Bulk or Monitors
Send many selected URLs to Bulk, or track a chosen page for changes with Monitors.
search api use casesSearch results without scraping the SERP.
Use POST /v1/search to get ranked public results and related
searches with country and language controls. Use search to find the right pages, then
send selected URLs to scrape, bulk, monitors, or screenshots when you need the page
behind the result.
E-commerce tracking
See how products, brands, and competitors show up across markets. Pull ranked results for target queries, compare regional result sets, and capture product pages when price, stock, or positioning matters.
Market research
Use live search results as a starting point for category research. Compare what ranks by country or language, collect related searches, and turn promising URLs into a clean dataset.
Search visibility research
See which public pages surface for a query: organic results, snippets, competing pages, and related searches. Use Search for discovery, then Scrape or Bulk for clean page content.
AI agents & data pipelines
Give agents and data systems current search context without building a search scraper. Return ranked URLs and related searches, then capture source pages only when the workflow needs evidence.
controlsShape the result set with request parameters.
All optional. Send them in the POST /v1/search body alongside
query.
type | web · news · images | Which result set to return. Defaults to web. |
date_range | any · hour · day · week · month · year | Restrict results by recency. |
country | two-letter code — us, de, jp | Bias results toward a region. |
language | ISO-639-1 — en, fr, es | Bias results toward a language. |
limit | 1 – 100 | How many ranked results to return. |
pick the right starting pointDon't know the URL, or already have the domain?
When to use Search
POST /v1/search
Find relevant public pages by query when you don't yet have the URL.
Good for research, source discovery, competitor pages, policy pages, docs, account pages, and seed-URL finding.
When to use Sitemap
POST /sitemap
Inventory the URLs on a known site when you already have the domain.
Good for docs sites, blogs, catalogs, and known domains. Returns a source-aware CSV your app selects from.
credit cost + boundariesCredit cost and boundaries.
Credit cost
credits_used = min(ceil(limit / 10), 10)
Results are fetched in pages of 10. Each fetched page costs one credit, capped at 10.
limit = 1 1 page 1 credit
limit = 10 1 page 1 credit
limit = 11 2 pages 2 credits
limit = 35 4 pages 4 credits
limit = 100 10 pages 10 credits
Every fetched result page is charged, even when a page returns fewer than 10 results.
Boundaries
Search does not retrieve page content. It returns candidate URLs, snippets, and metadata only.
No automatic Scrape, Bulk, Schema, or Monitor action — you make the next call.
REST-only today. Search is not exposed through the current MCP tools.
Ranking is provider-returned candidate ordering, not a ByteKit trust signal.
Candidate URLs require your review before you retrieve or track them.
faq
What does the Search API do?
The Search API returns ranked search results for a query, including titles, URLs, snippets when available, and related searches when the provider returns them. It helps you discover relevant pages before deciding what to scrape, monitor, or analyze.
Is Search the same as scraping?
No. Search helps you find pages; scraping extracts content from a specific page. Use /search to discover URLs, then use /scrape when you need the content behind one of those results.
What kinds of search results can I request?
You can search across web, news, or images. Web search returns ranked organic results, news search adds publisher and thumbnail details when available, and image search returns image metadata such as source, domain, image URL, and thumbnail details.
Can I control how many results come back?
Yes. You can request between 1 and 100 results with limit. Results are returned in one response and re-ranked with clean position values starting at 1.
Does Search support country, language, or freshness filters?
Yes. You can set a two-letter country, a two-letter ISO language code, and a recency window such as past hour, day, week, month, or year.
How are searches charged?
Search is billed by result pages, not by individual results. Results are fetched in pages of 10, so limit=10 costs 1 credit, limit=35 costs 4 credits, and limit=100 costs 10 credits. The response includes credits_used.
Do news, image, and recency searches cost more?
No. Billing is based on the requested result count, not the search type or recency filter. Web, news, and image searches with the same limit use the same number of credits.
Does Search support pagination?
Not as a public page-by-page API. You choose a limit, and ByteKit handles the internal paging, merging, ranking, and truncation into one response.
pricingSame API on every plan. Pay for what you use.
Search is billed in pages of 10 results, one credit per page. Every plan supports the same API — start on PAYG with a one-time free balance, then pay for usage.
| PAYG free balance | 50 MB + 100 credits |
| PAYG bandwidth | $8 / GB |
| Monthly plans | from $29 / mo |
| Cache hits · failed | 50% · $0 |
Run a real query through Search.
Create a free API key and send one query through /v1/search. See
the ranked URLs your product would actually retrieve.