> ## Documentation Index
> Fetch the complete documentation index at: https://docs.plyne.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Search web

> Call web_search through the Plyne API or MCP. Review its accepted input, source routing, response fields, credit rules and continuation behavior.

Search the web using Google or Parallel. Select one source or an ordered fallback chain. Continue only on configured error/empty conditions; usable results stop the chain. Source-specific options pin their source. Returns common results and source-specific additional\_fields.

## Usage

* Default source order is Parallel then Google. Select one routing.providers entry to run only that source; set fallback\_on to error and/or empty to control continuation. Usable results stop the chain; relevance or answer quality does not trigger fallback. Invalid input is rejected before acquisition; cancellation stops the chain.
* Google-specific provider\_options.google pins Google; Parallel-specific provider\_options.parallel pins Parallel. Filters are never dropped to enable fallback.
* The plan pricing is the maximum reservation: Google costs 0.1 credits per usable page, Parallel 0.2. Only the source producing the returned data is charged. Source prices are listed in source\_pricing.
* Results share URL, title and excerpts. Google-specific fields are retained in data.additional\_fields.google. Google AI Overview accepts a Google-source web\_search run ID. Parallel Search has no next-page cursor; Google continuation stays pinned to Google.
* Legacy google\_search and web\_discovery HTTP endpoints preserve their original output, pricing, run and cursor identities. Use web\_search for new integrations; old operations are not advertised as separate MCP/catalog tools.

## API

Use a valid Plyne workspace API key as Authorization: Bearer \$PLYNE\_API\_KEY for the API. Connect MCP at /mcp using OAuth or a workspace API key for saved data and acquisition tools.

```bash theme={null}
curl "$PLYNE_API_URL/v1/tools/web_search/execute" \
  -H "Authorization: Bearer $PLYNE_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: REPLACE_WITH_UNIQUE_REQUEST_ID' \
  --data '{
  "query": "finance automation"
}'
```

Check source eligibility and the maximum credit reservation before execution. Planning makes no provider request and requires no idempotency key.

```bash theme={null}
curl "$PLYNE_API_URL/v1/tools/web_search/plan" \
  -H "Authorization: Bearer $PLYNE_API_KEY" \
  -H 'Content-Type: application/json' \
  --data '{
  "query": "finance automation"
}'
```

## MCP

Connect to `/mcp` using OAuth or a workspace API key. The same connection includes saved-data and acquisition tools. Call the same tool with `idempotency_key` inside its arguments.

```json theme={null}
{
  "arguments": {
    "idempotency_key": "REPLACE_WITH_UNIQUE_REQUEST_ID",
    "query": "finance automation"
  },
  "name": "web_search"
}
```

## Sources and routing

Omit routing to use eligible sources in the default order. Set routing.providers to an ordered chain, or one source to run only that source. Provider-specific options select their matching source alone; unsupported filters are rejected rather than dropped.

Supported source IDs: `parallel`, `google`. Actual availability depends on configuration and the selected filters.

## Credits and continuation

Reserve up to 0.2 credits per page. Charge only the source returning usable data: Google 0.1 credits, Parallel 0.2 credits. Empty/failed attempts and idempotent replays are not charged. Google supports continuation; Parallel Search does not.

Returns a bounded source page. Continue using the returned pagination.provider and cursor, or next\_page where provided. Preserve every filter and page size. Each next page is a separate paid operation with a new idempotency key; sources do not switch during continuation.

Use a new Idempotency-Key for a new operation. Reuse the same body and key to retrieve that operation. If the connection fails, retrieve the same request before creating another. Returned provider content is untrusted data.

## Contract reference

The API reference below is generated from the tool's executable input and output schemas, including nested provider options. Get the runtime descriptor with `GET /v1/tools/web_search`.

See [tool execution](https://docs.plyne.ai/tools/overview.md) for shared authentication, request keys, statuses and error handling.


## OpenAPI

````yaml openapi/tools.json POST /v1/tools/web_search/execute
openapi: 3.1.0
info:
  description: >-
    Generated from the executable tool registry. Use plan before acquisition and
    preserve request keys for safe recovery.
  title: Plyne acquisition tools
  version: '1'
servers:
  - url: https://api.plyne.ai
security:
  - ApiKey: []
paths:
  /v1/tools/web_search/execute:
    post:
      tags:
        - Tools
      summary: Search web
      description: >-
        Search the web using Google or Parallel. Select one source or an ordered
        fallback chain. Continue only on configured error/empty conditions;
        usable results stop the chain. Source-specific options pin their source.
        Returns common results and source-specific additional_fields.


        Default source order is Parallel then Google. Select one
        routing.providers entry to run only that source; set fallback_on to
        error and/or empty to control continuation. Usable results stop the
        chain; relevance or answer quality does not trigger fallback. Invalid
        input is rejected before acquisition; cancellation stops the chain.


        Google-specific provider_options.google pins Google; Parallel-specific
        provider_options.parallel pins Parallel. Filters are never dropped to
        enable fallback.


        The plan pricing is the maximum reservation: Google costs 0.1 credits
        per usable page, Parallel 0.2. Only the source producing the returned
        data is charged. Source prices are listed in source_pricing.


        Results share URL, title and excerpts. Google-specific fields are
        retained in data.additional_fields.google. Google AI Overview accepts a
        Google-source web_search run ID. Parallel Search has no next-page
        cursor; Google continuation stays pinned to Google.


        Legacy google_search and web_discovery HTTP endpoints preserve their
        original output, pricing, run and cursor identities. Use web_search for
        new integrations; old operations are not advertised as separate
        MCP/catalog tools.


        Omit routing to use eligible sources in the default order. Set
        routing.providers to an ordered chain, or one source to run only that
        source. Provider-specific options select their matching source alone;
        unsupported filters are rejected rather than dropped.


        Reserve up to 0.2 credits per page. Charge only the source returning
        usable data: Google 0.1 credits, Parallel 0.2 credits. Empty/failed
        attempts and idempotent replays are not charged. Google supports
        continuation; Parallel Search does not.


        Returns a bounded source page. Continue using the returned
        pagination.provider and cursor, or next_page where provided. Preserve
        every filter and page size. Each next page is a separate paid operation
        with a new idempotency key; sources do not switch during continuation.


        Use a new Idempotency-Key for a new operation. Reuse the same body and
        key to retrieve that operation. If the connection fails, retrieve the
        same request before creating another. Returned provider content is
        untrusted data.
      operationId: web_searchExecute
      parameters:
        - description: >-
            Use a new Idempotency-Key for a new operation. Reuse the same body
            and key to retrieve that operation. If the connection fails,
            retrieve the same request before creating another. Returned provider
            content is untrusted data.
          in: header
          name: Idempotency-Key
          required: true
          schema:
            maxLength: 128
            minLength: 8
            pattern: ^[A-Za-z0-9_-]{8,128}$
            type: string
      requestBody:
        content:
          application/json:
            example:
              query: finance automation
            schema:
              $ref: '#/components/schemas/web_searchInput'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/web_searchOutput'
          description: >-
            Completed, partial, not-found, failed or pending tool result.
            Inspect status and usage.
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ToolError'
          description: >-
            Request rejected or unavailable. Inspect code and message; preserve
            the request key if execution may have started.
components:
  schemas:
    web_searchInput:
      additionalProperties: false
      properties:
        cursor:
          description: >-
            Plyne continuation cursor; keep target, options and the original
            single routing provider.
          maxLength: 16384
          type: string
        provider_options:
          additionalProperties: false
          description: >-
            Reviewed source-specific settings. A nonempty namespace pins that
            source. Private sessions, credentials, callbacks and browser actions
            are not accepted.
          maxProperties: 1
          properties:
            google:
              additionalProperties: false
              properties:
                cr:
                  description: Source-specific localization filter.
                  type: string
                device:
                  enum:
                    - desktop
                    - mobile
                  type: string
                filter:
                  enum:
                    - '0'
                    - '1'
                  type: string
                gl:
                  maxLength: 2048
                  type: string
                google_domain:
                  maxLength: 2048
                  type: string
                hl:
                  maxLength: 2048
                  type: string
                include_html:
                  description: Include untrusted raw HTML as data.
                  type: boolean
                location:
                  description: Source-specific localization filter.
                  type: string
                lr:
                  description: Source-specific localization filter.
                  type: string
                nfpr:
                  description: Disable automatic spelling correction.
                  type: boolean
                safe:
                  enum:
                    - active
                  type: string
                time_period:
                  enum:
                    - last_hour
                    - last_day
                    - last_week
                    - last_month
                    - last_year
                  type: string
                uule:
                  description: Source-specific localization filter.
                  type: string
              type: object
            parallel:
              additionalProperties: false
              properties:
                advanced_settings:
                  additionalProperties: false
                  properties:
                    excerpt_settings:
                      additionalProperties: false
                      properties:
                        max_chars_per_result:
                          maximum: 100000
                          minimum: 1
                          type: integer
                      type: object
                    fetch_policy:
                      additionalProperties: false
                      properties:
                        disable_cache_fallback:
                          description: Do not fall back to cached pages.
                          type: boolean
                        max_age_seconds:
                          maximum: 31536000
                          minimum: 0
                          type: integer
                        timeout_seconds:
                          maximum: 60
                          minimum: 1
                          type: number
                      type: object
                    location:
                      pattern: ^[A-Za-z]{2}$
                      type: string
                    max_results:
                      maximum: 25
                      minimum: 1
                      type: integer
                    source_policy:
                      additionalProperties: false
                      properties:
                        after_date:
                          pattern: ^[0-9]{4}-[0-9]{2}-[0-9]{2}$
                          type: string
                        exclude_domains:
                          items:
                            maxLength: 253
                            type: string
                          maxItems: 100
                          type: array
                        include_domains:
                          items:
                            maxLength: 253
                            type: string
                          maxItems: 100
                          type: array
                      type: object
                  type: object
                client_model:
                  description: Client model hint.
                  type: string
                max_chars_total:
                  maximum: 200000
                  minimum: 1
                  type: integer
                mode:
                  enum:
                    - turbo
                    - fast
                    - basic
                    - advanced
                  type: string
                objective:
                  description: Research goal. Common query supplies search_queries.
                  type: string
              type: object
          type: object
        query:
          description: Search query or topic.
          maxLength: 2048
          minLength: 1
          type: string
        routing:
          additionalProperties: false
          dependentRequired:
            fallback_on:
              - providers
          description: >-
            Optional source chain. One source runs alone; multiple sources are
            tried in order. All selected sources must support the request.
            Provider options require a matching one-source chain.
          properties:
            fallback_on:
              description: >-
                When to try the next source. Defaults to error and empty; has no
                effect for one source.
              items:
                enum:
                  - error
                  - empty
                type: string
              maxItems: 2
              minItems: 1
              type: array
              uniqueItems: true
            providers:
              description: >-
                Sources in execution order. One entry uses only that source.
                Omit to use the default chain.
              items:
                enum:
                  - parallel
                  - google
                type: string
              maxItems: 2
              minItems: 1
              type: array
              uniqueItems: true
          type: object
      required:
        - query
      type: object
    web_searchOutput:
      additionalProperties: false
      properties:
        data:
          additionalProperties: false
          properties:
            additional_fields:
              additionalProperties: false
              properties:
                google:
                  properties:
                    ai_overview:
                      properties:
                        references:
                          items:
                            properties:
                              index:
                                type: integer
                              link:
                                type: string
                              snippet:
                                type: string
                              source:
                                type: string
                              source_icon:
                                type: string
                              thumbnail:
                                type: string
                              title:
                                type: string
                            type: object
                          type: array
                        session_key:
                          type: string
                        state:
                          type: string
                        text_blocks:
                          items:
                            properties:
                              cards:
                                items:
                                  properties:
                                    link:
                                      type: string
                                    snippet:
                                      type: string
                                    title:
                                      type: string
                                  type: object
                                type: array
                              level:
                                type: integer
                              list:
                                items:
                                  properties:
                                    list:
                                      items:
                                        properties:
                                          list:
                                            items:
                                              properties:
                                                list: {}
                                                reference_indexes:
                                                  items:
                                                    type: integer
                                                  type: array
                                                shopping_result:
                                                  properties:
                                                    extracted_old_price:
                                                      type: number
                                                    extracted_price:
                                                      type: number
                                                    index:
                                                      type: integer
                                                    old_price:
                                                      type: string
                                                    price:
                                                      type: string
                                                    product_link:
                                                      type: string
                                                    rating:
                                                      type: number
                                                    reviews:
                                                      type: integer
                                                    source:
                                                      type: string
                                                    thumbnail:
                                                      type: string
                                                    title:
                                                      type: string
                                                  type: object
                                                snippet:
                                                  type: string
                                                snippet_links:
                                                  items:
                                                    properties:
                                                      link:
                                                        type: string
                                                      text:
                                                        type: string
                                                    type: object
                                                  type: array
                                              type: object
                                            type: array
                                          reference_indexes:
                                            items:
                                              type: integer
                                            type: array
                                          shopping_result:
                                            properties:
                                              extracted_old_price:
                                                type: number
                                              extracted_price:
                                                type: number
                                              index:
                                                type: integer
                                              old_price:
                                                type: string
                                              price:
                                                type: string
                                              product_link:
                                                type: string
                                              rating:
                                                type: number
                                              reviews:
                                                type: integer
                                              source:
                                                type: string
                                              thumbnail:
                                                type: string
                                              title:
                                                type: string
                                            type: object
                                          snippet:
                                            type: string
                                          snippet_links:
                                            items:
                                              properties:
                                                link:
                                                  type: string
                                                text:
                                                  type: string
                                              type: object
                                            type: array
                                        type: object
                                      type: array
                                    reference_indexes:
                                      items:
                                        type: integer
                                      type: array
                                    shopping_result:
                                      properties:
                                        extracted_old_price:
                                          type: number
                                        extracted_price:
                                          type: number
                                        index:
                                          type: integer
                                        old_price:
                                          type: string
                                        price:
                                          type: string
                                        product_link:
                                          type: string
                                        rating:
                                          type: number
                                        reviews:
                                          type: integer
                                        source:
                                          type: string
                                        thumbnail:
                                          type: string
                                        title:
                                          type: string
                                      type: object
                                    snippet:
                                      type: string
                                    snippet_links:
                                      items:
                                        properties:
                                          link:
                                            type: string
                                          text:
                                            type: string
                                        type: object
                                      type: array
                                  type: object
                                type: array
                              reference_indexes:
                                items:
                                  type: integer
                                type: array
                              snippet:
                                type: string
                              snippet_links:
                                items:
                                  properties:
                                    link:
                                      type: string
                                    text:
                                      type: string
                                  type: object
                                type: array
                              type:
                                type: string
                            type: object
                          type: array
                      type: object
                    bottom_ads:
                      items:
                        properties:
                          description:
                            type: string
                          displayed_url:
                            type: string
                          phone:
                            type: string
                          position:
                            type: integer
                          title:
                            type: string
                          url:
                            type: string
                        type: object
                      type: array
                    discussions_and_forums:
                      items:
                        properties:
                          community:
                            type: string
                          date:
                            type: string
                          link:
                            type: string
                          position:
                            type: integer
                          source:
                            type: string
                          title:
                            type: string
                        type: object
                      type: array
                    html:
                      type: string
                    knowledge_graph:
                      additionalProperties: {}
                      type: object
                    local_map:
                      properties:
                        gps_coordinates:
                          additionalProperties:
                            type: number
                          type: object
                        image:
                          type: string
                        link:
                          type: string
                      type: object
                    local_results:
                      properties:
                        more_locations_link:
                          type: string
                        places:
                          items:
                            properties:
                              position:
                                type: integer
                              price:
                                type: string
                              rating:
                                type: number
                              title:
                                type: string
                            type: object
                          type: array
                      type: object
                    navigation:
                      items:
                        properties:
                          title:
                            type: string
                          url:
                            type: string
                        type: object
                      type: array
                    organic_results:
                      items:
                        properties:
                          date:
                            type: string
                          displayed_link:
                            type: string
                          link:
                            type: string
                          position:
                            type: integer
                          rich_snippet:
                            additionalProperties: {}
                            type: object
                          sitelinks:
                            additionalProperties: {}
                            type: object
                          snippet:
                            type: string
                          snippet_highlighted_words:
                            items:
                              type: string
                            type: array
                          source:
                            type: string
                          title:
                            type: string
                        type: object
                      type: array
                    pagination:
                      properties:
                        current:
                          type: integer
                        next:
                          type: string
                        other_pages:
                          additionalProperties:
                            type: string
                          type: object
                      type: object
                    related_questions:
                      items:
                        properties:
                          question:
                            type: string
                        type: object
                      type: array
                    related_searches:
                      items:
                        properties:
                          link:
                            type: string
                          query:
                            type: string
                        type: object
                      type: array
                    search_information:
                      properties:
                        city:
                          type: string
                        country:
                          type: string
                        organic_results_state:
                          type: string
                        page_title:
                          type: string
                        query_displayed:
                          type: string
                        results_for:
                          type: string
                        time_taken_displayed:
                          type: number
                        total_results:
                          type: integer
                      type: object
                    search_parameters:
                      properties:
                        cr:
                          type: string
                        device:
                          type: string
                        filter:
                          type: string
                        gl:
                          type: string
                        google_domain:
                          type: string
                        hl:
                          type: string
                        location:
                          type: string
                        lr:
                          type: string
                        nfpr:
                          type: boolean
                        q:
                          type: string
                        safe:
                          type: string
                        start:
                          type: integer
                        time_period:
                          type: string
                        uule:
                          type: string
                      type: object
                    top_ads:
                      items:
                        properties:
                          description:
                            type: string
                          displayed_url:
                            type: string
                          phone:
                            type: string
                          position:
                            type: integer
                          title:
                            type: string
                          url:
                            type: string
                        type: object
                      type: array
                    top_stories:
                      items:
                        properties:
                          items:
                            items:
                              properties:
                                link:
                                  type: string
                                position:
                                  type: integer
                                title:
                                  type: string
                              type: object
                            type: array
                        type: object
                      type: array
                    video_results:
                      items:
                        properties:
                          duration:
                            type: string
                          position:
                            type: integer
                          source:
                            type: string
                          title:
                            type: string
                          url:
                            type: string
                        type: object
                      type: array
                  type: object
              type: object
            results:
              items:
                additionalProperties: false
                properties:
                  excerpts:
                    items:
                      type: string
                    type: array
                  published_at:
                    description: Publication timestamp when available.
                    type: string
                  title:
                    description: Result title.
                    type: string
                  url:
                    description: Public result URL.
                    type: string
                type: object
              type: array
          type:
            - object
            - 'null'
        error:
          additionalProperties: false
          properties:
            code:
              type: string
            message:
              type: string
            retryable:
              type: boolean
          required:
            - code
            - message
            - retryable
          type:
            - object
            - 'null'
        fulfillment:
          properties:
            field_sources:
              additionalProperties:
                items:
                  properties:
                    observation_id:
                      type: string
                    observed_at:
                      properties: {}
                      type: object
                    provider:
                      type: string
                    url:
                      type: string
                  type: object
                type: array
              type: object
            missing_fields:
              items:
                type: string
              type: array
            satisfied:
              type: boolean
          type: object
        id:
          type: string
        pagination:
          additionalProperties: false
          properties:
            cursor:
              type: string
            has_more:
              type:
                - boolean
                - 'null'
            limit:
              maximum: 100
              minimum: 1
              type: integer
            next_page:
              minimum: 0
              type:
                - integer
                - 'null'
            page:
              minimum: 0
              type: integer
            provider:
              enum:
                - parallel
                - google
              type: string
            returned:
              maximum: 100
              minimum: 0
              type: integer
            total:
              minimum: 0
              type:
                - integer
                - 'null'
          required:
            - page
            - limit
            - returned
            - total
            - has_more
            - next_page
          type: object
        routing:
          additionalProperties: false
          properties:
            attempts:
              items:
                additionalProperties: false
                properties:
                  outcome:
                    enum:
                      - success
                      - partial
                      - pending
                      - error
                      - empty
                    type: string
                  provider:
                    type: string
                  requests:
                    minimum: 0
                    type: integer
                required:
                  - provider
                  - outcome
                  - requests
                type: object
              type: array
            mode:
              enum:
                - auto
                - single
                - fallback
              type: string
            selected_provider:
              type: string
          required:
            - mode
          type: object
        sources:
          items:
            additionalProperties: false
            properties:
              observation_id:
                type: string
              observed_at:
                format: date-time
                type: string
              provider:
                type: string
              url:
                type: string
            required:
              - provider
            type: object
          type: array
        status:
          enum:
            - completed
            - partial
            - not_found
            - failed
            - pending
          type: string
        tool:
          const: web_search
          type: string
        usage:
          additionalProperties: false
          properties:
            credit_units:
              minimum: 0
              type: integer
            credits:
              type: string
            unit:
              const: page
              type: string
          required:
            - credit_units
            - credits
            - unit
          type:
            - object
            - 'null'
        version:
          const: '1'
          type: string
        warnings:
          items:
            additionalProperties: false
            properties:
              code:
                type: string
              message:
                type: string
            required:
              - code
              - message
            type: object
          type: array
      required:
        - id
        - tool
        - version
        - status
        - data
        - sources
        - usage
        - error
      type: object
    ToolError:
      properties:
        code:
          type: string
        message:
          type: string
      required:
        - code
        - message
      type: object
  securitySchemes:
    ApiKey:
      scheme: bearer
      type: http

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.