> ## Documentation Index > Fetch the complete documentation index at: https://docs.paywithlocus.com/llms.txt > Use this file to discover all available pages before exploring further. # Run Web Research > With effort set, returns a grounded answer with citations. Without effort, uses the legacy structured-source or multi-provider evidence contract. ## OpenAPI ````yaml /api-reference/openapi.json post /wrapped/credits/router/web-research openapi: 3.1.0 info: title: Locus Pro API description: >- Access paid tools, manage prepaid balances, and build usage billing. Send money as exact decimal strings and reuse Idempotency-Key on retries. Management routes require a scoped server key or authorized dashboard session. Sensitive workspace changes require an owner or admin with recent MFA or passkey verification, except where an operation documents a stricter boundary. Interactive agents use MCP OAuth; unattended agents use scoped Agent Connections. Browser widgets use end-user tokens. version: 0.7.0 servers: - url: https://api.paywithlocus.com/api description: Production - url: https://api.stage.paywithlocus.com/api description: Stage — evaluation and integration testing security: - secretKey: [] tags: - name: Authentication description: Email-verified self-serve account creation and dashboard identity - name: Tenants description: Tenant profile, keys, and settings (dashboard session or secret key) - name: Workspace members description: Invite-only human workspace membership and role administration - name: Catalog description: Enable/disable APIs and set markups - name: Custom APIs description: Feature-gated enterprise BYOK providers and schema-backed custom actions - name: End users description: End-user accounts, tokens, and allocations - name: Top-ups description: Locus-hosted checkout top-ups and quotes - name: Ledger description: Burn/top-up history and earnings - name: Webhooks description: Signed events, delivery inspection, and replay - name: Burn description: Metered pay-per-use calls - name: MCP description: Stateless Streamable HTTP transport and MCP tool-result contracts - name: Okibi Identity description: >- Feature-gated Okibi identity verification and scoped native CLI credential bootstrap - name: Widget description: End-user JWT surface; a matching publishable key is optional - name: Agent-native onboarding description: >- Self-registration, human Stripe funding handoff, and restricted account setup for headless agents - name: Hosted Workflows description: >- Tenant-private TypeScript Workflow definitions, immutable versions, bounded runs, artifacts, and recovery - name: Agent connections description: Scoped, expiring, revocable credentials for agent execution - name: Recipes description: >- Search, research, extraction, enrichment, and travel outcomes across providers paths: /wrapped/credits/router/web-research: post: tags: - Recipes summary: Run Web Research description: >- With effort set, returns a grounded answer with citations. Without effort, uses the legacy structured-source or multi-provider evidence contract. parameters: - $ref: '#/components/parameters/SessionBindingHeader' - name: Idempotency-Key in: header required: true schema: type: string minLength: 1 maxLength: 255 description: Reuse the same value only when retrying the same logical request. requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/LocusWebResearchRequest' responses: '200': description: Result, sources, and billing receipt content: application/json: schema: $ref: '#/components/schemas/LocusWebResearchResponse' '400': $ref: '#/components/responses/BadRequest' '402': description: Insufficient credits '403': description: Capability, provider, policy, or spend limit denied the request '409': description: The aggregate tenant-aware estimate exceeds maxCredits security: - secretKey: [] - endUserToken: [] - agentConnection: [] components: parameters: SessionBindingHeader: name: X-Locus-Session-Id in: header required: false schema: type: string minLength: 16 maxLength: 128 pattern: ^[A-Za-z0-9][A-Za-z0-9._:-]{15,127}$ description: >- Required only when the end-user JWT carries sid. Send the original high-entropy session value; sid is its SHA-256 fingerprint. Ignored for secret-key authentication. schemas: LocusWebResearchRequest: type: object properties: query: type: string pattern: ^\s*(?:\S|\S[\s\S]{0,398}\S)\s*$ description: Search or research request. maxResults: type: integer minimum: 1 maximum: 20 default: 10 mode: type: string enum: - fast - balanced - comprehensive default: balanced maxProviders: type: integer minimum: 1 maximum: 13 default: 4 strategy: type: string enum: - balanced - cost - quality - speed description: Legacy mode selector retained for compatible clients. topic: type: string enum: - general - news default: general recencyDays: type: integer minimum: 1 maximum: 365 country: type: string pattern: ^[A-Za-z]{2}$ includeDomains: type: array maxItems: 20 items: type: string minLength: 1 pattern: \S excludeDomains: type: array maxItems: 20 items: type: string minLength: 1 pattern: \S includeImages: type: boolean default: false providers: type: array maxItems: 13 items: type: string pattern: >- ^\s*(?:[aA][gG][eE][nN][tT]402|[aA][gG][eE][nN][tT][sS][tT][oO][oO][lL][sS]|[aA][nN][dD][iI]|[bB][rR][aA][vV][eE]|[dD][aA][tT][aA][fF][oO][rR][sS][eE][oO]|[eE][xX][aA]|[fF][iI][rR][eE][cC][rR][aA][wW][lL]|[lL][iI][nN][kK][uU][pP]|[pP][aA][rR][aA][lL][lL][eE][lL]|[pP][eE][rR][pP][lL][eE][xX][iI][tT][yY]|[sS][eE][lL][tT][zZ]|[sS][eE][rR][pP][eE][rR]|[tT][aA][vV][iI][lL][yY])\s*$ description: >- Provider ID. Available values: agent402, agentstools, andi, brave, dataforseo, exa, firecrawl, linkup, parallel, perplexity, seltz, serper, tavily. Matching ignores case and surrounding whitespace. maxCredits: oneOf: - type: string pattern: >- ^\s*(?=[0-9.]{1,100}\s*$)0*(?:(?:[1-9]\d{0,11})(?:\.\d{1,6})?|1000000000000(?:\.0{1,6})?|0\.(?=\d{0,5}[1-9])\d{1,6})\s*$ - type: number exclusiveMinimum: 0 maximum: 1000000000000 description: >- Aggregate hard charge ceiling in workspace credits. Decimal strings support up to six fractional digits; numeric values are rounded down to six digits. rails: type: array items: type: string enum: - api-key - mpp - x402 description: Legacy access-path field retained for compatible clients. externalUserId: type: string minLength: 1 pattern: \S description: Optional end-user billing attribution for a tenant secret key. attribution: type: object additionalProperties: true description: Optional JSON ledger metadata such as a task or customer identifier. effort: type: string enum: - light - medium - heavy description: >- Explicitly request a grounded answer. Omit only for the legacy evidence-only contract. outputSchema: type: object description: >- Optional bounded JSON object schema for the answer. Requires effort and preserves the same grounded-reference envelope. properties: type: const: object properties: type: object maxProperties: 100 additionalProperties: true required: type: array maxItems: 100 uniqueItems: true items: type: string minLength: 1 description: Declared properties omitted here are optional. additionalProperties: const: false description: type: string maxLength: 2000 required: - type - properties - required - additionalProperties additionalProperties: false required: - query additionalProperties: false dependentRequired: outputSchema: - effort LocusWebResearchResponse: type: object properties: object: const: locus.web_research capability: const: web.research routerVersion: const: 2026-09-14.v28 query: type: string objective: type: string enum: - find_sources - structured_answer - resolved_answer partial: type: boolean answer: type: string references: type: array items: type: object properties: id: type: string url: type: string format: uri title: type: string startIndex: type: integer minimum: 0 endIndex: type: integer minimum: 0 required: - id - url additionalProperties: false completionStatus: type: string enum: - complete - partial stopReason: type: string enum: - completed - provider_incomplete effort: type: string enum: - light - medium - heavy output: oneOf: - type: 'null' - type: boolean - type: number - type: string - type: array items: {} - type: object additionalProperties: true description: Exact JSON value returned by the selected structured endpoint. evidence: type: array items: type: object properties: kind: type: string enum: - structured_data - web_page title: type: string url: type: string format: uri excerpt: type: string publishedAt: type: string score: type: number minimum: 0 maximum: 1 sourceCount: type: integer minimum: 1 required: - kind - title - url - sourceCount additionalProperties: false images: type: array items: type: object properties: url: type: string format: uri title: type: string sourceUrl: type: string format: uri required: - url additionalProperties: false structuredData: type: object properties: format: const: json source: type: object properties: name: type: string url: type: string format: uri required: - name - url additionalProperties: false value: oneOf: - type: 'null' - type: boolean - type: number - type: string - type: array items: {} - type: object additionalProperties: true description: Exact JSON value returned by the selected structured endpoint. required: - format - source - value additionalProperties: false route: oneOf: - type: object properties: strategy: const: web_search successfulProviders: type: integer minimum: 0 attemptedProviders: type: integer minimum: 0 required: - strategy - successfulProviders - attemptedProviders additionalProperties: false - type: object properties: strategy: const: structured_source provider: type: string endpoint: type: string reason: type: string successfulProviders: type: integer minimum: 0 attemptedProviders: type: integer minimum: 0 fallbackUsed: const: false required: - strategy - provider - endpoint - reason - successfulProviders - attemptedProviders - fallbackUsed additionalProperties: false - type: object properties: strategy: const: structured_source_fallback provider: type: string endpoint: type: string reason: type: string successfulProviders: type: integer minimum: 0 attemptedProviders: type: integer minimum: 0 fallbackUsed: const: true fallbackReason: type: string required: - strategy - provider - endpoint - reason - successfulProviders - attemptedProviders - fallbackUsed - fallbackReason additionalProperties: false - type: object properties: strategy: const: grounded_answer provider: const: Parallel endpoint: const: responses successfulProviders: type: integer minimum: 0 attemptedProviders: type: integer minimum: 1 modelTurns: type: integer minimum: 1 searches: type: integer minimum: 0 fetches: type: integer minimum: 0 required: - strategy - provider - endpoint - successfulProviders - attemptedProviders - modelTurns - searches - fetches additionalProperties: false billing: type: object properties: chargedCredits: type: string pattern: ^\d+(?:\.\d+)?$ successfulProviders: type: integer minimum: 0 attemptedProviders: type: integer minimum: 0 required: - chargedCredits - successfulProviders - attemptedProviders additionalProperties: false routingPolicy: type: object properties: requestedMode: type: string enum: - shadow - canary - enforce effectiveMode: type: string enum: - static - shadow - canary - enforce policyId: type: string predictedRouteId: type: string predictedDecision: type: string enum: - single - multi confidence: type: number minimum: 0 maximum: 1 accepted: type: boolean applied: type: boolean fallbackReason: type: string enum: - policy_unavailable - artifact_not_eligible - unsupported_request - low_confidence - shadow_only - canary_holdout - route_unavailable required: - requestedMode - effectiveMode - accepted - applied additionalProperties: false required: - object - capability - routerVersion - query - objective - partial - evidence - images - route - billing oneOf: - properties: objective: const: structured_answer route: properties: strategy: const: structured_source required: - strategy required: - structuredData - properties: objective: const: find_sources route: properties: strategy: enum: - web_search - structured_source_fallback required: - strategy not: required: - structuredData - properties: objective: const: resolved_answer route: properties: strategy: const: grounded_answer required: - strategy required: - answer - references - completionStatus - stopReason - effort not: required: - structuredData additionalProperties: false responses: BadRequest: description: >- The request is malformed or fails local validation before any provider or payment action. securitySchemes: secretKey: type: http scheme: bearer description: Tenant secret key (lcr_…). Server-side only. endUserToken: type: http scheme: bearer description: >- 60-3600 second end-user JWT minted via /credits/end-users/{id}/token. If the JWT has sid, send the original session value in X-Locus-Session-Id; sid contains only its SHA-256 fingerprint. Bearer tokens are replayable until expiry; use short TTLs, optional session binding, and Idempotency-Key on operations. agentConnection: type: http scheme: bearer description: >- Scoped lcac_ credential. Tenant-managed Agent Connections authorize only their bound MCP and wrapped execution surfaces. A bootstrap connection for a self-registered agent additionally authorizes the explicit /credits/agent/* self-service routes for its own account; neither form authorizes general tenant management. ````