Response Format

Understand asynchronous operation statuses, progress, citations, and result fields.

Search, Scrape, Seed, and Crawl are asynchronous. Create returns an operation ID, then the matching read route returns progress until a terminal state.

Search statuses

StatusMeaning
pendingThe operation was created but work has not started.
planningThe retrieval strategy is being prepared.
searchingNodes are gathering relevant sources.
processingSources are being processed and analyzed.
aggregatingThe final answer is being assembled.
completedTerminal success state with a result.
failedTerminal failure state; inspect the error fields when present.
cancelledTerminal cancellation state.

Other operation types may expose a smaller status set, but clients should always stop polling when the response reaches a terminal state.

Search response example

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "completed",
  "query": "What is OptimAI Search?",
  "progress": {
    "stage": "completed",
    "percent": 100,
    "sources_found": 24,
    "sources_analyzed": 18,
    "sources_relevant": 7
  },
  "result": {
    "answer": "OptimAI Search is a decentralized Web3 search engine...",
    "summary": "A shorter answer summary.",
    "citations": [
      {
        "id": 1,
        "url": "https://example.com/article",
        "title": "Example source",
        "snippet": "Supporting context..."
      }
    ]
  }
}

Fields to keep

  • id: stable operation ID for polling, support, and idempotent retries.
  • status: lifecycle state used to decide whether to poll or finish.
  • progress: optional stage, percentage, and source counts while work runs.
  • result.answer: the completed Search answer.
  • result.citations: source URLs, titles, snippets, and related metadata.
  • result: operation-specific output for Scrape, Seed, and Crawl.
  • error: failure details when the operation fails or is rejected.

Render the answer together with its citations. Keeping evidence visible makes it easier for users to check an important claim and for operators to debug a result.

Scrape, Seed, and Crawl statuses

Mining-style operations use a smaller lifecycle:

StatusMeaning
pendingThe job is accepted but work has not started.
runningA worker is processing the job.
completedTerminal success with an operation-specific result.
failedTerminal failure; inspect the error response when present.
cancelledTerminal cancellation; reserved credits are refunded by the API.

Empty citations are valid

For Search responses, result.citations is always an array, but it may be empty for a successful operation. Treat the answer and status as the success signal; do not assume an empty citation list means the transport failed.

For x402 Search responses, x402_payment_status is present in addition to the normal Search fields. See x402 SDK for the payment status lifecycle.