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": [
    "https://techcrunch.com/ai-startup-series-b",
    "https://www.reuters.com/technology/ai-funding-round"
  ],
  "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), not price.amount: price.amount is the per-source cost plus margin before the flat $0.001 transaction fee, while accepts[0].amount is the exact USDC (6-decimal) amount you will be charged — for the default 10 sources that is 263500, i.e. $0.2635. 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 pricing is per-source with a 5% BlockRun margin, plus the flat $0.001 per-transaction fee charged on every paid call:

• Base cost: $0.025 per source
• Margin: 5%
• Transaction fee: $0.001 per request (flat)
• Formula: max_results × $0.025 × 1.05 + $0.001

The price depends only on max_results, not on how many sources you list in sources or how many the search actually used.

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?