Skip to content

search.md

Latest commit

 

History

History
156 lines (124 loc) · 4.45 KB

search.md

File metadata and controls

156 lines (124 loc) · 4.45 KB
Raw

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.
country string or null No Unset Optional country code used by the upstream search provider.
page integer No 1 Must be between 1 and 100.
results_per_page integer No 10 Must be between 1 and 100. Billing is 20 credits per 10 requested results.

Compatibility

POST /v1/search is the primary public search entry point. Legacy endpoints such as POST /v1/search/page and POST /v1/search/news remain available for existing integrations, but new integrations should send channel to POST /v1/search.

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, cache_timestamp, credits_used, title, final_url, 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.
  • Search responses are cached for 1 hour by channel, query, country, page, and results_per_page.
  • Search cache hits keep the same pricing. A non-zero cache_timestamp indicates the response was served from the gateway cache.

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",
  results_per_page: 10,
});

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,
  })
  .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",
    }
)

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

curl

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

Example Response

{
  "ok": true,
  "query": "openai agents sdk",
  "status_code": 200,
  "cache_timestamp": 0,
  "credits_used": 20,
  "title": "OpenAI Agents SDK",
  "final_url": "https://openai.github.io/openai-agents-python/",
  "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
  • 429 RATE_LIMIT_REACHED or UPSTREAM_RATE_LIMITED
  • 502 UPSTREAM_CONNECTION_FAILED or UPSTREAM_BAD_RESPONSE
  • 503 DATABASE_NOT_CONFIGURED or SEARCH_PROVIDER_NOT_CONFIGURED
  • 504 UPSTREAM_TIMEOUT