API Reference

Base URL: https://api.krawl.sh

Version: 0.2.0

AuthenticationCopy Anchor Link

Most endpoints accept an optional API key via the X-API-Key header. Behavior depends on how the server is configured:

• krawl_* keys are validated against the keys table (multi-user, plan-scoped, revocable, expirable).
• A legacy single KRAWL_DEV_KEY is honored for backward compatibility.
• If neither is configured, auth is disabled (development only).

curl -H "X-API-Key: your-key" https://api.krawl.sh/health

When auth is enabled and the key is wrong, missing, revoked, or expired:

{"detail": "Invalid, revoked, or expired API key"}

The research endpoints (/research, /research/upload, /templates/{id}/research, /v1/chat/completions) also support keyless pay-per-request via x402 when enabled. Admin-only endpoints require a separate KRAWL_ADMIN_KEY. See Authentication for the full model.

Rate limits, retries & statusCopy Anchor Link

Idempotency-Key replays eligible successful JSON responses for up to 24 hours. Authentication and key-management routes under /auth, token issuance at /agent/auth, requests carrying the session cookie or an Authorization header, legacy or unknown X-API-Key credentials, ZDR requests, ephemeral evidence exports, SSE, no-store and Set-Cookie responses bypass this response cache. Authentication always runs again for these requests; a retry of key issuance can create a new key. Do not rely on this header to recover a lost credential. Previously cached responses are invalidated when this security update is deployed.

Rate limit: 5 requests/minute per IP by default (some endpoints set their own limits, noted below). Every response carries X-RateLimit-Limit / X-RateLimit-Remaining / RateLimit-Policy headers so you can self-throttle.

When you exceed a limit the API returns 429 Too Many Requests with a Retry-After header (delta-seconds) and a structured envelope ({ "error_code": "RATE_LIMITED", "retry_after": 60, ... }). Agents must honor Retry-After and apply exponential backoff + jitter on 429/5xx. See the full Rate Limits & Retries playbook for thresholds, the 429 envelope, and a concrete backoff loop.

• Batch/bulk: POST /research/batch queues up to 20 jobs in one call.
• Status: live status page and /status.json; programmatic GET /health. Use these to determine retry eligibility and recover from failure streaks (error-recovery playbook).

HealthCopy Anchor Link

GET /healthCopy Anchor Link

Liveness and readiness check, including database connectivity.

Auth: None.

curl https://api.krawl.sh/health

Response:

{
  "status": "ok",
  "version": "0.2.0",
  "db": "ok",
  "uptime_seconds": 1234.5
}

status is ok when the database is reachable, otherwise degraded. db is ok or error.

ResearchCopy Anchor Link

POST /researchCopy Anchor Link

Execute deep research and stream events via SSE. This is the primary endpoint.

Auth: API key (or keyless x402 when enabled).

Request body:

Source policy:

{
  "source_policy": {
    "include_domains": ["arxiv.org", "nature.com"],
    "exclude_domains": ["medium.com"],
    "freshness": "30d"
  }
}

freshness accepts windows like 7d, 30d, 90d, 1y.

Response: SSE stream. See SSE Events for all event types.

curl -N -X POST https://api.krawl.sh/research \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-key" \
  -d '{"query": "AI agents 2025", "mode": "deep", "breadth": 4, "depth_levels": 3}'

If output_schema is invalid, the request fails with 422 before the stream starts.

POST /research/uploadCopy Anchor Link

Research with uploaded document context. Multipart form data. Returns the same SSE stream as /research.

Auth: API key (or keyless x402 when enabled).

Form fields:

curl -N -X POST https://api.krawl.sh/research/upload \
  -H "X-API-Key: your-key" \
  -F "query=Analyze the findings in these documents" \
  -F "mode=deep" \
  -F "files=@report.pdf" \
  -F "files=@data.csv"

Empty file slots are ignored. An invalid mode or too many files returns 422.

POST /playgroundCopy Anchor Link

Run a real research stream with no API key. This is the homepage playground, a marketing and activation surface, not a free API tier.

Auth: None. Heavily constrained: forced quick mode, short query cap, tiny cost ceiling, per-IP rate limit (15/hour, raised from 3/hour in 2026-06 to fit small teams behind corporate NAT — see /rate-limits), and results are NOT persisted. Returns 404 if the playground is disabled.

Request body:

curl -N -X POST https://api.krawl.sh/playground \
  -H "Content-Type: application/json" \
  -d '{"query": "What is Uniswap v4?"}'

Response: SSE stream (same event shape as /research).

POST /research/compareCopy Anchor Link

Compare research results to detect changes over time. Returns a structured diff with new findings, removed claims, changed metrics, and a natural language summary.

Auth: API key.

Request body:

curl -X POST https://api.krawl.sh/research/compare \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-key" \
  -d '{"query": "ETH staking yields"}'

Response:

{
  "old_result_id": "uuid",
  "new_result_id": "uuid",
  "old_query": "ETH staking yields",
  "new_query": "ETH staking yields",
  "old_created_at": "2026-05-01T00:00:00Z",
  "new_created_at": "2026-05-29T00:00:00Z",
  "changes": [],
  "new_findings": [],
  "removed_claims": [],
  "summary": "...",
  "has_changes": true
}

POST /research/{research_id}/steerCopy Anchor Link

Inject a steering instruction into an active research session. The research_id is the session ID emitted at the start of the SSE stream.

The latest queued instruction applies before the next agent turn in quick mode, or query-generation call in recursive modes, including child research nodes. It carries into synthesis/refinement, report scope and requested structured output without rerunning completed searches. The audit precedes the result so disconnecting after the report preserves its applied controls. The steer SSE event identifies the instruction consumed at that boundary; instructions superseded before a boundary do not produce an applied event. An in-flight provider call continues under its existing request. Durable pause/resume and branch cancellation are not supported.

Auth: API key.

Request body:

curl -X POST https://api.krawl.sh/research/550e8400-e29b-41d4-a716-446655440000/steer \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-key" \
  -d '{"instruction": "Focus on regulatory risk in the EU"}'

Response:

{
  "status": "instruction_queued",
  "research_id": "550e8400-e29b-41d4-a716-446655440000",
  "instruction": "Focus on regulatory risk in the EU"
}

Returns 404 if there is no active session with that ID.

Async TasksCopy Anchor Link

Submit research to run server-side without holding an SSE connection, then poll for status.

POST /research/asyncCopy Anchor Link

Submit a research job to run in the background. Returns immediately with 202.

Auth: API key. Quota is enforced up front, and a per-key cap bounds concurrent fan-out (returns 429 when exceeded).

Request body:

curl -X POST https://api.krawl.sh/research/async \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-key" \
  -d '{"query": "State of L2 rollups", "mode": "deep"}'

Response (202):

{
  "id": "uuid",
  "query": "State of L2 rollups",
  "mode": "deep",
  "status": "queued",
  "result_id": null,
  "error": null,
  "created_at": "2026-05-29T00:00:00Z",
  "started_at": null,
  "finished_at": null
}

status is one of queued, running, done, error.

GET /tasksCopy Anchor Link

List the caller's async tasks, newest first.

Auth: API key.

Query params: limit (default 50, clamped to 1 to 100), offset (default 0).

curl https://api.krawl.sh/tasks?limit=20 \
  -H "X-API-Key: your-key"

Response: an array of task objects (same shape as above).

GET /tasks/{task_id}Copy Anchor Link

Poll a single async task. When status is done, fetch the report via GET /results/{result_id}.

Auth: API key.

curl https://api.krawl.sh/tasks/uuid \
  -H "X-API-Key: your-key"

Returns 404 if the task is not found. Response is a single task object.

OpenAI-compatibleCopy Anchor Link

Point any OpenAI SDK (or LangChain, LlamaIndex, etc.) at Krawl by setting base_url to this server.

POST /v1/chat/completions and POST /chat/completionsCopy Anchor Link

OpenAI-compatible Chat Completions. The model selects the research mode and the last user message is the research query. Returns a fully cited report as the assistant message. Supports streaming and non-streaming.

Auth: API key (or keyless x402 when enabled).

Request body:

Unknown fields (temperature, top_p, tools, etc.) are accepted and ignored so existing OpenAI callers work unchanged.

curl -X POST https://api.krawl.sh/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-key" \
  -d '{
    "model": "krawl-deep",
    "messages": [{"role": "user", "content": "Compare Solana and Aptos"}]
  }'

Response (non-streaming): a standard OpenAI chat.completion object with the report in choices[0].message.content. Returns 422 if there is no user message content to research.

GET /v1/models and GET /modelsCopy Anchor Link

List the available krawl-* research models in OpenAI's format.

Auth: None enforced beyond the default rate limit.

curl https://api.krawl.sh/v1/models

Response:

{
  "object": "list",
  "data": [
    {"id": "krawl-deep", "object": "model", "owned_by": "krawl"}
  ]
}

TemplatesCopy Anchor Link

Reusable research prompts with fillable variables.

GET /templatesCopy Anchor Link

List all available research templates.

Auth: API key.

curl https://api.krawl.sh/templates \
  -H "X-API-Key: your-key"

Response: {"templates": [...]}

GET /templates/{template_id}Copy Anchor Link

Get a specific template by ID. Returns 404 if not found.

Auth: API key.

curl https://api.krawl.sh/templates/token-deep-dive \
  -H "X-API-Key: your-key"

POST /templates/{template_id}/researchCopy Anchor Link

Execute a template with filled-in variables. Returns an SSE stream (same as /research). The template's own mode is used.

Auth: API key (or keyless x402 when enabled).

Request body:

curl -N -X POST https://api.krawl.sh/templates/token-deep-dive/research \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-key" \
  -d '{"variables": {"token": "ETH"}}'

Returns 404 for an unknown template and 422 if required variables are missing.

Results & SessionsCopy Anchor Link

GET /resultsCopy Anchor Link

List persisted research results.

Auth: API key (results are scoped to the key).

Query params: offset (default 0), limit (default 50, 1 to 100).

curl https://api.krawl.sh/results?limit=10 \
  -H "X-API-Key: your-key"

Response: {"results": [...]}

GET /results/{result_id}Copy Anchor Link

Retrieve a specific result. The result_id must be a UUID. Returns 404 if not found.

Auth: API key.

curl https://api.krawl.sh/results/550e8400-e29b-41d4-a716-446655440000 \
  -H "X-API-Key: your-key"

GET /results/{result_id}/exportCopy Anchor Link

Export a result as HTML, PDF, Markdown, DOCX, or a slide deck.

Auth: API key.

Query params:

curl -L "https://api.krawl.sh/results/550e8400-e29b-41d4-a716-446655440000/export?format=pdf" \
  -H "X-API-Key: your-key" \
  -o report.pdf

Returns the rendered file with an appropriate Content-Type and Content-Disposition. Returns 404 if the result is not found.

GET /sessions/{session_id}Copy Anchor Link

Return all research results in a session, ordered by creation time. The session_id must be a UUID.

Auth: API key.

curl https://api.krawl.sh/sessions/550e8400-e29b-41d4-a716-446655440000 \
  -H "X-API-Key: your-key"

Response:

{
  "session_id": "550e8400-e29b-41d4-a716-446655440000",
  "results": [...]
}

Returns 404 if the session does not exist or has no results.

GET /audit/{result_id}Copy Anchor Link

Get the audit trail for a research result: per-step search, extract, learn, gap-detect, synthesize, and verify actions with timing and token usage.

Auth: API key.

curl https://api.krawl.sh/audit/550e8400-e29b-41d4-a716-446655440000 \
  -H "X-API-Key: your-key"

Response:

{
  "result_id": "550e8400-e29b-41d4-a716-446655440000",
  "entries": [
    {
      "timestamp": "2026-05-29T00:00:00Z",
      "action": "search",
      "tool": "webSearch",
      "query": "...",
      "sources_found": 8,
      "learnings_extracted": 3,
      "model": "...",
      "tokens_used": 1200,
      "duration_ms": 850.0
    }
  ]
}

Returns 404 if there is no audit trail for the result.

SearchCopy Anchor Link

POST /searchCopy Anchor Link

Execute a single-source search and return JSON results. This is not the full research pipeline, it queries one source directly.

Auth: API key.

Request body:

Common options keys: num_results (clamped to 1 to 30, default 8), category, start_date, include_domains (Exa); from_date, to_date, include_handles, exclude_handles (X); token_id (crypto); url (web and media, fetches or transcribes a specific URL).

curl -X POST https://api.krawl.sh/search \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-key" \
  -d '{"query": "restaking protocols", "source": "exa", "options": {"num_results": 10}}'

Response: shape varies by source. Most sources return {"sources": [...]}. X also returns text, citations, and tweets. GitHub adds repos. Crypto returns token, tvl, and/or search_results.

{
  "sources": [
    {
      "url": "https://example.com",
      "title": "...",
      "content": "...",
      "published_date": null,
      "source_type": "exa",
      "author": null,
      "favicon": null,
      "credibility_tier": null
    }
  ]
}

LookoutsCopy Anchor Link

Scheduled recurring research tasks.

POST /lookoutsCopy Anchor Link

Create a new lookout. Enforces a per-key limit (returns 429 when reached).

Auth: API key.

Request body:

curl -X POST https://api.krawl.sh/lookouts \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-key" \
  -d '{"query": "Base ecosystem news", "mode": "quick", "schedule": "daily"}'

Response: the created lookout object.

{
  "id": "uuid",
  "query": "Base ecosystem news",
  "mode": "quick",
  "schedule": "daily",
  "active": true,
  "last_run": null,
  "last_result_id": null,
  "created_at": "2026-05-29T00:00:00Z",
  "webhook_url": null
}

GET /lookoutsCopy Anchor Link

List lookouts.

Auth: API key.

Query params: offset (default 0), limit (default 50, 1 to 100).

curl https://api.krawl.sh/lookouts \
  -H "X-API-Key: your-key"

Response: {"lookouts": [...]}

GET /lookouts/{lookout_id}Copy Anchor Link

Get a specific lookout. UUID required. Returns 404 if not found.

Auth: API key.

DELETE /lookouts/{lookout_id}Copy Anchor Link

Delete a lookout. Returns 404 if not found.

Auth: API key.

curl -X DELETE https://api.krawl.sh/lookouts/uuid \
  -H "X-API-Key: your-key"

Response: {"deleted": true}

POST /lookouts/{lookout_id}/runCopy Anchor Link

Manually trigger a lookout run. Rate-limited to 2/minute and subject to a per-lookout cooldown (returns 429 if triggered too soon after the last run, or 503 if the server is busy).

Auth: API key.

curl -X POST https://api.krawl.sh/lookouts/uuid/run \
  -H "X-API-Key: your-key"

Response: the run result.

MemoryCopy Anchor Link

Cross-session knowledge base of prior research findings.

GET /memoryCopy Anchor Link

Search the knowledge base.

Auth: API key.

Query params: q (required, max 500 chars), limit (default 20, 1 to 100).

curl "https://api.krawl.sh/memory?q=staking&limit=10" \
  -H "X-API-Key: your-key"

Response:

{
  "query": "staking",
  "count": 3,
  "memories": [
    {
      "id": "uuid",
      "content": "...",
      "source_query": "...",
      "source_urls": ["..."],
      "tags": ["..."],
      "created_at": "2026-05-29T00:00:00Z",
      "result_id": "uuid"
    }
  ]
}

Returns 400 if q is empty.

GET /memory/statsCopy Anchor Link

Statistics about the knowledge base.

Auth: API key.

curl https://api.krawl.sh/memory/stats \
  -H "X-API-Key: your-key"

DELETE /memory/{memory_id}Copy Anchor Link

Delete a specific memory entry. UUID required. Returns 404 if not found.

Auth: API key.

curl -X DELETE https://api.krawl.sh/memory/uuid \
  -H "X-API-Key: your-key"

Response: {"deleted": true, "id": "uuid"}

AskCopy Anchor Link

POST /askCopy Anchor Link

NLWeb-compatible natural language query endpoint. Accepts a question and returns a structured answer pointing the caller to the right research endpoint. Optionally streams NLWeb-style SSE events (start, result, complete).

Auth: API key.

Request body:

curl -X POST https://api.krawl.sh/ask \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-key" \
  -d '{"query": "How do I research a token?"}'

Response:

{
  "_meta": {"response_type": "answer", "version": "0.1", "provider": "krawl.sh"},
  "query": "How do I research a token?",
  "answer": "Use the /research endpoint for deep research on: How do I research a token?",
  "sources": [],
  "suggested_endpoint": "/research",
  "auth": {"method": "api_key", "header": "X-API-Key", "signup": "https://krawl.sh"}
}

MCPCopy Anchor Link

POST /mcp and GET /mcpCopy Anchor Link

Model Context Protocol server over Streamable HTTP (JSON-RPC 2.0). Agent platforms call POST /mcp to initialize, tools/list, and tools/call. Discovery methods are never gated; only tools/call execution is authenticated (X-API-Key, or keyless x402 when enabled). GET /mcp returns server metadata and the tool list.

See Agents & MCP for the full integration guide.

curl -X POST https://api.krawl.sh/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}'

Auth & KeysCopy Anchor Link

See Authentication for the complete model. Key issuance and listing are admin-only and require KRAWL_ADMIN_KEY.

POST /auth/demo-keyCopy Anchor Link

Generate a rate-limited demo API key for testing. No auth required. The key is hashed at rest and expires in 24 hours. Rate-limited to 3/hour.

curl -X POST https://api.krawl.sh/auth/demo-key

Response:

{
  "api_key": "krawl_demo_...",
  "type": "demo",
  "plan": "demo",
  "rate_limit": "...",
  "monthly_search_credits": 0,
  "monthly_deep_krawls": 0,
  "expires_in": "24 hours",
  "note": "Demo key for testing. Sign up at krawl.sh for full access."
}

POST /auth/keysCopy Anchor Link

Issue a new API key. The raw key is returned exactly once.

Auth: Admin (KRAWL_ADMIN_KEY).

Request body:

curl -X POST https://api.krawl.sh/auth/keys \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $KRAWL_ADMIN_KEY" \
  -d '{"plan": "pro", "name": "acme prod", "owner_email": "ops@acme.com"}'

GET /auth/keysCopy Anchor Link

List API key metadata. Never returns raw keys.

Auth: Admin (KRAWL_ADMIN_KEY).

Query params: owner_email (optional, max 255 chars).

curl "https://api.krawl.sh/auth/keys?owner_email=ops@acme.com" \
  -H "X-API-Key: $KRAWL_ADMIN_KEY"

Response: {"keys": [{"prefix": "...", "plan": "...", "name": "...", "owner_email": "...", "active": true, "created_at": "...", "last_used_at": "...", "expires_at": "...", "revoked_at": "..."}]}

DELETE /auth/keysCopy Anchor Link

Revoke the krawl_ key presented in the X-API-Key header (self-service). Rate-limited to 20/minute.

Auth: the key being revoked.

curl -X DELETE https://api.krawl.sh/auth/keys \
  -H "X-API-Key: krawl_live_..."

Response: {"revoked": true}. Returns 404 if the key is not found or already revoked.

Usage & BillingCopy Anchor Link

GET /usageCopy Anchor Link

Return the caller's usage for the current (or given) month plus plan quotas. Requires a krawl_ API key. Rate-limited to 60/minute.

Auth: krawl_ API key.

Query params: period (optional, format YYYY-MM).

curl https://api.krawl.sh/usage \
  -H "X-API-Key: krawl_live_..."

Response:

{
  "plan": "pro",
  "period": "2026-05",
  "usage": {"deep_krawls": 12, "search_credits": 340, "total_tokens": 1200000, "cost_usd": 4.231},
  "limits": {"monthly_deep_krawls": 100, "monthly_search_credits": 5000, "rate_limit": "..."},
  "remaining": {"deep_krawls": 88, "search_credits": 4660}
}

remaining values are null for unlimited (negative-limit) plans.

GET /usage/eventsCopy Anchor Link

Return recent per-request usage events for the caller's key. Rate-limited to 60/minute.

Auth: krawl_ API key.

Query params: limit (default 50, 1 to 200).

curl https://api.krawl.sh/usage/events \
  -H "X-API-Key: krawl_live_..."

Response: {"events": [...]}

POST /billing/checkoutCopy Anchor Link

Start a Stripe Checkout session to upgrade the caller's key to Pro. Only krawl_live_ keys can be upgraded. Rate-limited to 10/minute. Returns 503 if billing is not enabled.

Auth: krawl_live_ API key.

Request body:

curl -X POST https://api.krawl.sh/billing/checkout \
  -H "Content-Type: application/json" \
  -H "X-API-Key: krawl_live_..." \
  -d '{"email": "ops@acme.com"}'

Response: a Stripe Checkout session (includes the hosted checkout URL).

POST /billing/portalCopy Anchor Link

Open the Stripe billing portal for the caller's linked customer. Rate-limited to 10/minute. Returns 400 if no billing account is linked, 503 if billing is disabled.

Auth: krawl_ API key.

curl -X POST https://api.krawl.sh/billing/portal \
  -H "X-API-Key: krawl_live_..."

Response: a Stripe billing portal session (includes the portal URL).

POST /billing/webhookCopy Anchor Link

Consume signature-verified Stripe webhook events and apply plan changes. Called by Stripe, not by API clients. Requires STRIPE_WEBHOOK_SECRET and a valid stripe-signature header.

Auth: Stripe signature.

Response: {"received": true, ...}. Returns 400 on invalid payload or signature, 503 for retryable reconciliation errors.

DiscoveryCopy Anchor Link

OAuth and x402 metadata that let agents discover how to authenticate and pay.

GET /.well-known/oauth-protected-resourceCopy Anchor Link

OAuth 2.0 Protected Resource metadata (RFC 9728).

Auth: None.

curl https://api.krawl.sh/.well-known/oauth-protected-resource

Response:

{
  "resource": "https://api.krawl.sh",
  "authorization_servers": ["https://api.krawl.sh"],
  "scopes_supported": ["research:read", "research:write", "results:read"],
  "bearer_methods_supported": ["header"],
  "resource_documentation": "https://docs.krawl.sh"
}

GET /.well-known/oauth-authorization-serverCopy Anchor Link

OAuth 2.0 Authorization Server metadata (RFC 8414) plus a WorkOS agent_auth discovery block.

Auth: None.

curl https://api.krawl.sh/.well-known/oauth-authorization-server

GET /discovery/resourcesCopy Anchor Link

Agent-payable resource discovery for x402 / MPP. Lists the API resources an agent can pay for per-request, with price, network, and asset, so an autonomous agent can discover costs without first triggering a 402.

Auth: None.

curl https://api.krawl.sh/discovery/resources

Response:

{
  "x402Version": 1,
  "enabled": true,
  "facilitator": "...",
  "resources": [
    {
      "resource": "https://api.krawl.sh/research",
      "method": "POST",
      "description": "Deep multi-source research report (cited markdown).",
      "x402": {
        "scheme": "exact",
        "network": "...",
        "asset": "...",
        "maxAmountRequired": "...",
        "priceUsd": 0.0,
        "payTo": null
      }
    }
  ],
  "payment_methods": ["x402", "api_key"],
  "auth_docs": "https://krawl.sh/auth.md"
}

Internal / experimentalCopy Anchor Link

Agentic commerce endpoints (/checkout-sessions, /checkout_sessions, /checkout_sessions/{session_id}, /agentic_commerce/delegate_payment) implement UCP/ACP checkout flows. They are internal and excluded from the public OpenAPI schema, and are subject to change.

Evidence time and accessCopy Anchor Link

Research sources carry optional retrieved_at (UTC), published_date, updated_date, date provenance, access_status, source_record_id and temporal_status. Missing fields on older reports mean unknown; never assign export time as retrieval time. Access states are inspected_text, partial_excerpt, provider_summary, metadata_only, fetch_failed, or unknown. These describe available evidence, not claim support or truth. A recent fetch does not make an old article current. Summary/metadata-only results do not establish that the original text was read.

Optional source_policy.as_of sets a UTC evidence cutoff; dates after it are quarantined in quarantined_sources, outside synthesis. Without it the cutoff is research start. This is not a historical web archive; undated content remains uncertain. See evidence methodology.

Evidence coverageCopy Anchor Link

The optional evidence_coverage result field gives descriptive counts of unique exact URLs discovered, explicitly fetched, retained, referenced in outgoing model input, and cited. Stages overlap: a retained search snippet may never have had its original page fetched. It also reports explicit failed/unavailable fetches, unknown fetch/access states, retained-host concentration, missing publication dates and their known range. A model-input reference may contain only metadata or a short excerpt; a citation is not a support verdict.

These counts do not establish representative sampling or correct selection bias. Hostnames do not prove independent origins; mirrors may share a publisher. Old reports without this field have unknown coverage. No extra LLM call is made; the measured instrumentation overhead is reported as measurement_overhead_ms, not a guarantee of zero added latency. See evidence methodology.