search.md

POST /v1/search

Run a public search through the AnyCrawler gateway. Use channel to choose the search vertical.

Authentication

• Authorization: Bearer <apiKey>
• x-api-key: <apiKey>

Stable Public Request Fields

Field	Type	Required	Default	Notes
channel	page, images, news, videos, or scholar	Yes	None	Selects the search vertical.
query	string	Yes	None	Search query string, at most 512 characters.
country	string or null	No	Unset	Optional country code used by the upstream search provider, at most 128 characters. Empty or whitespace-only values are normalized to null.
page	integer	No	1	Logical result page between 1 and 100. It is mapped with results_per_page onto consecutive 10-result provider pages.
results_per_page	integer	No	10	Must be between 1 and 100. Requests stop early when a provider page returns fewer than 10 primary results.

Contract Boundary

/v1/search exposes only the stable public search request fields above. Do not rely on undocumented passthrough parameters.

Response Behavior

• The response uses the normalized AnyCrawler search envelope: top-level ok, query, status_code, credits_used, and results.
• results.search_parameters mirrors the stable public request fields in snake_case, including channel.
• Backend response blocks are normalized to snake_case under results.
• Primary result lists are channel-specific: page and scholar use results.organic; images, news, and videos use results.images, results.news, and results.videos.
• Credits are reserved for the requested maximum and settled at 2 credits per primary result actually returned; unused reserved credits are returned.
• Optional normalized result blocks include knowledge_graph, people_also_ask, related_searches, and answer_box when the selected channel returns them.

Examples

Shared SDK files: TypeScript, JavaScript, Python, curl

TypeScript

import { AnyCrawlerClient } from "../shared/sdks/typescript/anycrawler";

const client = new AnyCrawlerClient({
  apiKey: process.env.ANYCRAWLER_API_KEY!,
});

const { data, meta } = await client.search({
  channel: "page",
  query: "openai agents sdk",
  country: "us",
  page: 2,
  results_per_page: 25,
});

console.log(data.results?.organic?.[0]?.title);
console.log(meta.creditsUsed);

JavaScript

const { AnyCrawlerClient } = require("../shared/sdks/javascript/anycrawler.js");

const client = new AnyCrawlerClient({
  apiKey: process.env.ANYCRAWLER_API_KEY,
});

client
  .search({
    channel: "news",
    query: "openai",
    country: "us",
    page: 1,
    results_per_page: 10,
  })
  .then(({ data }) => {
    console.log(data.results.news?.[0]?.link);
  });

Python

from anycrawler import AnyCrawlerClient
import os

client = AnyCrawlerClient(api_key=os.environ["ANYCRAWLER_API_KEY"])
response = client.search(
    {
        "channel": "videos",
        "query": "openai agents sdk",
        "country": "us",
        "results_per_page": 30,
    }
)

print(response["data"]["results"]["videos"][0]["title"])
print(response["meta"]["creditsUsed"])

curl

ANYCRAWLER_API_KEY="sk-your-key" \
CHANNEL="page" \
QUERY="openai agents sdk" \
RESULTS_PER_PAGE="25" \
./shared/sdks/curl/search.sh

Example Response

{
  "ok": true,
  "query": "openai agents sdk",
  "status_code": 200,
  "credits_used": 2,
  "results": {
    "search_parameters": {
      "channel": "page",
      "query": "openai agents sdk",
      "country": "us",
      "page": 1,
      "results_per_page": 10
    },
    "organic": [
      {
        "position": 1,
        "title": "OpenAI Agents SDK",
        "link": "https://openai.github.io/openai-agents-python/",
        "snippet": "Build agents with tools, handoffs, guardrails, and tracing."
      }
    ]
  }
}

Status Codes

• 200 on success
• 400 INVALID_REQUEST
• 401 INVALID_API_KEY
• 402 INSUFFICIENT_CREDITS
• 403 ACCOUNT_NOT_ACTIVE
• 409 RESERVATION_CONFLICT
• 413 PAYLOAD_TOO_LARGE
• 429 RATE_LIMIT_REACHED
• 502 UPSTREAM_CONNECTION_FAILED or UPSTREAM_BAD_RESPONSE
• 503 DATABASE_NOT_CONFIGURED or SEARCH_PROVIDER_NOT_CONFIGURED
• 504 UPSTREAM_TIMEOUT

Provider pages, key fallback and cache-fill waits share the gateway execution budget. A successful search still bills the actual returned result count, including a normal short final provider page. A failed or timed-out page does not silently become a newly introduced partially charged response. Preserve the response request ID when investigating an interrupted request; network delivery and financial commit cannot be made atomic.