---
title: "Lookup"
method: POST
path: "/v2/lookup"
tags: ["v2", "v2-lookup"]
---

# Lookup

`POST /v2/lookup`

## Request

- Base URL: `https://api.enconvert.com` (the document declares no server; this is the origin it was published from)
- URL: `https://api.enconvert.com/v2/lookup`
- Auth: none declared

Search the web via Serper, optionally auto-perceiving top results.

## Headers

- `X-API-Key` string, nullable
- `authorization` string, nullable

## Request body

- LookupRequest: One /v2/lookup request (plan section 4 / section 8 Task H.3). ``extra="forbid"``: unknown keys 422 with the field name instead of being silently dropped (2026-08-06 QA root-cause report, fix A1).
  - `query` string, required
  - `category` 'web' | 'news' | 'images' | 'scholar' | 'patents' | 'maps'
  - `country` string, nullable: Google 'gl' country code (e.g. 'us', 'in').
  - `locale` string, nullable: Google 'hl' interface language (e.g. 'en').
  - `time_filter` 'hour' | 'day' | 'week' | 'month' | 'year', nullable: Restrict to results from the past hour / day / week / month / year.
  - `num_results` integer: Serper 'num' page size (results per page).
  - `page` integer
  - `location` string, nullable: Full-text location string (e.g. 'Austin, Texas').
  - `autocorrect` boolean
  - `perceive_top` integer: Auto-perceive the top-N result URLs through /v2/perceive. Each one is a full browser render that runs sequentially through the shared singleton and consumes one perceive operation from your quota, so this is capped low; use /v2/perceive/batch for larger sets. 0 disables auto-perceive.
  - `enrich` LookupEnrich: Optional high-value enrichment for /v2/lookup's top-N results. When present (with ``perceive_top > 0``), the top-N result URLs are rendered CONCURRENTLY (bounded) in the requested output formats — not just markdown, and not one-at-a-time — and can additionally run schema-driven structured extraction per result and synthesize one cited answer across them. This is what makes lookup beat a plain "search + scrape".
    - `outputs` string[]: Perceive outputs to produce per enriched result (markdown, html_cleaned, links, screenshot, structured, ...). Defaults to markdown.
    - `concurrency` integer: How many result URLs to enrich in parallel. Markdown/HTML renders use the no-browser TLS path and truly parallelize; screenshot/pdf renders serialize on the shared browser.
    - `schema` object, nullable: When set, run structured extraction against each enriched result (JSON-Schema object or flat {field: description} map). The extracted data appears under each result's perceive.structured.
    - `synthesize_answer` boolean: Synthesize one cited, grounded answer to the query across the enriched results (LLM). Returned on the response as 'answer'.
    - `answer_prompt` string, nullable: Optional question to answer instead of the raw query (only used when synthesize_answer is true).

## Response `200`

Successful Response

- LookupResponse: Search results + provenance for one /v2/lookup call.
  - `lookup_id` integer, nullable: ch_lookup_queries row id for support correlation (null if the audit write failed; the results are still valid).
  - `query` string, required
  - `category` 'web' | 'news' | 'images' | 'scholar' | 'patents' | 'maps', required
  - `country` string, nullable
  - `locale` string, nullable
  - `time_filter` 'hour' | 'day' | 'week' | 'month' | 'year', nullable
  - `total` integer
  - `results` LookupResult[]
    - `title` string, nullable
    - `url` string, nullable
    - `snippet` string, nullable
    - `position` integer, nullable
    - `source` string, nullable
    - `date` string, nullable
    - `image_url` string, nullable
    - `thumbnail_url` string, nullable
    - `extra` object
    - `perceive` PerceiveResponse
      - `operation_id` string, required
      - `status` 'queued' | 'processing' | 'completed' | 'failed', required
      - `url` string, required
      - `url_final` string, nullable
      - `content_hash` string, nullable
      - `status_code` integer, nullable: HTTP status of the final main-document response (e.g. 200, 404). None when the engine could not observe it.
      - `render_quality` number, nullable: 0.0-1.0; populated by the F.7 scorer.
      - `deductions` object: Named render-quality deductions that fired for this render (e.g. {'http_error': 0.7}). Empty on a clean render.
      - `is_blocked` boolean: True when the scorer judged the render an anti-bot challenge or WAF block page. A block with no page content behind it returns 200 with this flag set and outputs={}.
      - `billed` boolean: Whether this operation consumed one op from the monthly quota. False for blocked reads and for renders whose deductions include http_error or login_wall; cache hits bill.
      - `options_echo` object, nullable: Echo of the request options the server honoured (secrets redacted to booleans), so a caller can verify what was actually applied.
      - `cache_hit` boolean
      - `outputs` object
      - `structured` object, nullable
      - `extraction_tier` 'heuristic' | 'css' | 'llm', nullable
      - `tokens` PerceiveTokens
        - `input` integer
        - `output` integer
      - `cost_cents` number
      - `duration_ms` integer, nullable
      - `error` string, nullable
      - `warnings` string[]
  - `perceive_top` integer: How many results were actually perceived (<= the requested perceive_top; lower if quota ran out or URLs failed).
  - `perceive_operation_ids` string[]
  - `answer_box` object, nullable
  - `knowledge_graph` object, nullable
  - `answer` string, nullable: Synthesized cited answer across the enriched results (present only when enrich.synthesize_answer is true and it succeeded).
  - `answer_sources` string[]: URLs used as grounding for 'answer', in citation order.
  - `credits` integer, nullable: Serper credits consumed by this query.
  - `cost_cents` number
  - `warnings` string[]

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/enconvert/apis/conversion-api.md) · [All operations](https://skmtc.dev/enconvert/apis/conversion-api/llms.txt) · [OpenAPI document](https://skmtc.dev/enconvert/apis/conversion-api/revisions/b8c820393569?raw)