> ## Documentation Index > Fetch the complete documentation index at: https://docs.revcenter.ai/llms.txt > Use this file to discover all available pages before exploring further. # Web search > Runs a web search and returns organic results plus the raw provider response. Billed per request as a metered acquisition event. Requires the `data:search:web` scope. ## OpenAPI ````yaml /openapi.json post /v1/data/search/web openapi: 3.1.0 info: title: Revcenter API description: >- Search, enrich, and activate people and companies. Two authentication surfaces share one host: the bearer-token API under `/v1` for server-to-server and agent use, and the workspace-session API under `/api` that the Revcenter app itself runs on. version: '2026-08-12' servers: - url: https://api.revcenter.ai description: Production security: - bearerAuth: [] tags: - name: Search description: Web search, search runs, results, exports, and shareable shortlists. - name: People description: Person search, profile enrichment, and the workspace contact pool. - name: Companies description: Company search, company enrichment, and org-chart people. - name: Campaigns description: Plan, publish, and launch outbound sequences on Smartlead and HeyReach. - name: Account description: Health, usage totals, and cost events. paths: /v1/data/search/web: post: tags: - Search summary: Web search description: >- Runs a web search and returns organic results plus the raw provider response. Billed per request as a metered acquisition event. Requires the `data:search:web` scope. operationId: searchWeb parameters: - $ref: '#/components/parameters/IdempotencyKeyHeader' requestBody: required: true content: application/json: schema: type: object required: - query properties: query: type: string minLength: 1 description: The search query. `q` is accepted as an alias. examples: - site:linkedin.com/in wealth advisor San Jose CFP surface: $ref: '#/components/schemas/SearchSurface' endpoint: $ref: '#/components/schemas/SearchSurface' num: type: integer minimum: 1 maximum: 100 default: 10 description: >- Results per page. Requests of 10 or fewer bill at the shallow rate; more than 10 bills at the deep rate. page: type: integer minimum: 1 maximum: 50 default: 1 gl: type: string description: Country code, e.g. `us`. examples: - us hl: type: string description: Language code, e.g. `en`. examples: - en location: type: string description: >- Geographic location string passed through to the search provider. idempotencyKey: type: string minLength: 8 maxLength: 160 description: >- Deduplicates billing when a request is retried. The `Idempotency-Key` header does the same thing. examples: linkedinSourcing: summary: Sourcing query scoped to LinkedIn profiles value: query: >- site:linkedin.com/in wealth advisor San Jose CFP impact investing num: 10 surface: search gl: us hl: en news: summary: News surface value: query: series B fintech Toronto surface: news num: 20 responses: '200': description: Search results. content: application/json: schema: allOf: - $ref: '#/components/schemas/MeteredEnvelope' - type: object properties: data: type: object properties: endpoint: type: string examples: - search results: type: array description: Organic results, when the surface returns them. items: type: object properties: title: type: string link: type: string format: uri snippet: type: string position: type: integer response: type: object description: >- The unmodified provider response, so surfaces without an `organic` array are still fully available. additionalProperties: true '400': $ref: '#/components/responses/InvalidRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/InsufficientScope' '424': $ref: '#/components/responses/ProviderUnavailable' '429': $ref: '#/components/responses/RateLimited' '502': $ref: '#/components/responses/ProviderError' security: - bearerAuth: [] components: parameters: IdempotencyKeyHeader: name: Idempotency-Key in: header required: false description: >- Deduplicates the billing event when a request is retried. Safe to send on every call. schema: type: string minLength: 8 maxLength: 160 schemas: SearchSurface: type: string enum: - search - images - news - maps - places - videos - shopping - scholar - patents - autocomplete default: search description: >- Which search surface to query. `endpoint` and `surface` are interchangeable. MeteredEnvelope: type: object description: The standard success envelope for billed endpoints. properties: data: type: object meta: allOf: - $ref: '#/components/schemas/Meta' - type: object properties: usage: $ref: '#/components/schemas/Usage' Meta: type: object properties: request_id: type: string format: uuid description: >- Echoes an inbound `X-Request-Id` when you send one, otherwise generated. Always returned in the `X-Request-Id` header too. Usage: type: object description: What this single call cost. properties: operation: type: string examples: - data.people.profile acquisition_units: type: integer examples: - 10000 billable_units: type: integer examples: - 10000 funding_source: $ref: '#/components/schemas/FundingSource' Error: type: object description: The error shape used by every `/v1` endpoint. properties: error: type: object properties: code: type: string examples: - insufficient_scope message: type: string details: type: object additionalProperties: true meta: $ref: '#/components/schemas/Meta' FundingSource: type: string enum: - platform - workspace_byok description: >- `platform` means Revcenter's own provider keys paid for the call and it counts as billable acquisition. `workspace_byok` means your workspace's own provider key did — the activity is recorded, but the vendor spend is yours, not billable overage. responses: InvalidRequest: description: The request body failed validation. content: application/json: schema: $ref: '#/components/schemas/Error' examples: missingQuery: value: error: code: invalid_request message: query is required. meta: request_id: 6f1c2b7e-9a3d-4c5f-8e21-0b7d4a9c1e33 Unauthorized: description: No key, or the key is invalid, expired, or revoked. content: application/json: schema: $ref: '#/components/schemas/Error' examples: missing: value: error: code: missing_api_key message: 'Send Authorization: Bearer rvc_live_...' meta: request_id: 6f1c2b7e-9a3d-4c5f-8e21-0b7d4a9c1e33 invalid: value: error: code: invalid_api_key message: API key is invalid, expired, or revoked. meta: request_id: 6f1c2b7e-9a3d-4c5f-8e21-0b7d4a9c1e33 InsufficientScope: description: The key authenticated but lacks the scope this endpoint requires. content: application/json: schema: $ref: '#/components/schemas/Error' examples: scope: value: error: code: insufficient_scope message: API key requires scope 'data:people:read'. meta: request_id: 6f1c2b7e-9a3d-4c5f-8e21-0b7d4a9c1e33 ProviderUnavailable: description: >- The workspace has no usable provider key for this capability — it is either unprovisioned or switched off. content: application/json: schema: $ref: '#/components/schemas/Error' examples: unavailable: value: error: code: provider_unavailable message: Web search is unavailable for this workspace. meta: request_id: 6f1c2b7e-9a3d-4c5f-8e21-0b7d4a9c1e33 RateLimited: description: >- The key exceeded its per-minute limit. Check `X-RateLimit-Reset` for when the window rolls over. content: application/json: schema: $ref: '#/components/schemas/Error' examples: limited: value: error: code: rate_limited message: API key rate limit exceeded. meta: request_id: 6f1c2b7e-9a3d-4c5f-8e21-0b7d4a9c1e33 ProviderError: description: The upstream data source failed. Nothing is billed. content: application/json: schema: $ref: '#/components/schemas/Error' examples: upstream: value: error: code: provider_error message: Harvest profile request failed meta: request_id: 6f1c2b7e-9a3d-4c5f-8e21-0b7d4a9c1e33 securitySchemes: bearerAuth: type: http scheme: bearer description: >- A Revcenter API key: `Authorization: Bearer rvc_live_...`. Keys are scoped, rate limited per key, and metered per workspace. ````