Search API

Real-time search across web and news using Grok AI.

Endpoint

POST https://blockrun.ai/api/v1/search

Request

Headers

Body Parameters

Source Types

Response

Success (200)

{
  "query": "latest AI funding rounds",
  "summary": "Several major AI companies have announced significant funding rounds...",
  "citations": [
    { "url": "https://techcrunch.com/ai-startup-series-b", "title": "techcrunch.com" },
    { "url": "https://www.reuters.com/technology/ai-funding-round", "title": "reuters.com" }
  ],
  "sources_used": 10,
  "model": "xai/grok-3-mini"
}

Response Fields

Successful responses also carry two headers: PAYMENT-RESPONSE (the x402 v2 settlement receipt — base64 JSON with success, transaction, network, payer) and X-Payment-Receipt (the on-chain settlement transaction hash).

Payment Required (402)

When you first make a request without payment, you'll receive:

{
  "x402Version": 2,
  "accepts": [{
    "scheme": "exact",
    "network": "eip155:8453",
    "amount": "263500",
    "asset": "0x8335…",
    "payTo": "0x…",
    "maxTimeoutSeconds": 300
  }],
  "error": "Payment Required",
  "message": "This endpoint requires x402 payment",
  "price": {
    "amount": "0.2625",
    "currency": "USD",
    "perSourceCost": 0.025,
    "maxResults": 10
  },
  "paymentInfo": {
    "network": "base",
    "asset": "USDC",
    "x402Version": 2
  }
}

The full x402 v2 payment requirements are in the X-Payment-Required and PAYMENT-REQUIRED headers (base64 JSON, identical content) and in WWW-Authenticate: X402 requirements="...", and are now also mirrored at the top of the JSON body as x402Version/accepts (for clients that only read the body). Sign against accepts[0].amount (header or body, they're identical): it is the exact USDC (6-decimal) amount you will be charged — 81000, i.e. $0.081, for every search. price.amount in the body is the same figure rounded to 4 decimals for display ("0.0810"), and price.perCallPrice is the $0.08 before the fee. Payment authorizations are valid for maxTimeoutSeconds: 300.

A GET to the same URL returns a 402 quoting the default price (10 sources) — useful for discovery.

Payment verification failed (402)

If a payment header is present but does not verify, the body carries a machine-readable code so a client can branch on it instead of parsing details:

{
  "error": "Payment verification failed",
  "code": "PAYMENT_UNFUNDED",
  "message": "The payment authorization could not be executed on-chain. ...",
  "details": "<raw verifier error>"
}

A 402 with error: "Payment settlement failed" means the search ran but settlement did not complete; nothing was charged.

Pricing

Search is $0.08 per call, plus the flat $0.001 per-transaction fee charged on every paid call — $0.081 in total, whatever max_results is.

It is one price because the work behind a search does not scale with max_results: each call runs as many searches as the query needs and reads the pages it finds, and that is what it costs. A per-result price would overcharge the default request and undercharge a small one.

(Before 2026-09-29 this endpoint charged max_results × $0.025 × 1.05 + $0.001 — $0.2635 at the default 10.)

Examples

Chat Completions Alternative

You can also access Grok's live search through the Chat Completions API by including search_parameters in your request:

{
  "model": "xai/grok-4.3",
  "messages": [{"role": "user", "content": "What's trending in AI today?"}],
  "search_parameters": {
    "mode": "on",
    "sources": [{"type": "web"}, {"type": "news"}],
    "max_search_results": 10,
    "return_citations": true
  }
}

This gives you the raw chat completion response with search-augmented context. The /v1/search endpoint provides a more structured search-specific response format.

Error Codes

Upstream calls are made only after payment verifies; settlement happens after the search returns, so a failed search is never charged.

Error Response

{
  "error": "Invalid request body",
  "details": [
    {
      "code": "too_small",
      "minimum": 1,
      "path": ["query"],
      "message": "String must contain at least 1 character(s)"
    }
  ]
}

What's next?