> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.usescout.sh/llms.txt.
> For full documentation content, see https://docs.usescout.sh/llms-full.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.usescout.sh/_mcp/server.

# Search

POST https://core.usescout.sh/v1/search
Content-Type: application/json

Run one or more web searches; return merged, de-duplicated results.

For `depth` in {instant, fast, auto} this is synchronous: the response is
the full `SearchResponse`. For `depth='deep'` the response is HTTP 202
with a `SearchRunView` carrying a `search_id` - poll
GET /v1/searches/{search_id}, stream events via SSE
(/v1/searches/{search_id}/events) or WebSocket
(/v1/searches/{search_id}/ws), or pass a `webhook` URL on the body to
receive the finished run.

Reference: https://docs.usescout.sh/api-reference/scout/search/post-v-1-search-post

## OpenAPI Specification

```yaml
openapi: 3.1.0
info:
  title: Scout
  version: 1.0.0
paths:
  /v1/search:
    post:
      operationId: post-v-1-search-post
      summary: Search
      description: >-
        Run one or more web searches; return merged, de-duplicated results.


        For `depth` in {instant, fast, auto} this is synchronous: the response
        is

        the full `SearchResponse`. For `depth='deep'` the response is HTTP 202

        with a `SearchRunView` carrying a `search_id` - poll

        GET /v1/searches/{search_id}, stream events via SSE

        (/v1/searches/{search_id}/events) or WebSocket

        (/v1/searches/{search_id}/ws), or pass a `webhook` URL on the body to

        receive the finished run.
      tags:
        - subpackage_search
      parameters:
        - name: Authorization
          in: header
          description: Your API key, sent as a Bearer token.
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                description: Any type
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SearchRequestV1'
servers:
  - url: https://core.usescout.sh
components:
  schemas:
    SearchRequestV1Depth:
      type: string
      enum:
        - instant
        - fast
        - auto
        - deep
      default: auto
      description: >-
        'instant' (~200ms, top of page, no enrichment), 'fast' (~450ms, single
        SERP page), 'auto' (~1s, recommended), 'deep' (~4-18s, multi-page gather
        + merge).
      title: SearchRequestV1Depth
    SearchRequestV1Mode:
      type: string
      enum:
        - basic
        - advanced
      description: >-
        Alias of `depth` (basic -> fast, advanced -> auto). If both are
        supplied, `depth` wins.
      title: SearchRequestV1Mode
    SearchRequestV1Category:
      type: string
      enum:
        - company
        - research_paper
        - news
        - personal_site
        - financial_report
        - people
      description: >-
        Result category hint. One of: company, research_paper, news,
        personal_site, financial_report, people.
      title: SearchRequestV1Category
    SearchRequestV1Freshness:
      type: string
      enum:
        - hour
        - day
        - week
        - month
        - year
      description: 'Restrict to recent results: hour, day, week, month or year.'
      title: SearchRequestV1Freshness
    SearchSourcePolicy:
      type: object
      properties:
        include_domains:
          type:
            - array
            - 'null'
          items:
            type: string
          description: Only return results whose URL is on these domains.
        exclude_domains:
          type:
            - array
            - 'null'
          items:
            type: string
          description: Drop results whose URL is on these domains.
        after_date:
          type:
            - string
            - 'null'
          description: Only return results published on or after this date (YYYY-MM-DD).
        before_date:
          type:
            - string
            - 'null'
          description: Only return results published on or before this date (YYYY-MM-DD).
      description: Where results may come from, and a publish-date window.
      title: SearchSourcePolicy
    SearchExcerptSettings:
      type: object
      properties:
        max_chars_per_result:
          type:
            - integer
            - 'null'
          description: >-
            Per-URL cap on excerpt characters (alias of top-level
            `max_excerpt_chars`).
      description: Per-call excerpt sizing for /v1/search.
      title: SearchExcerptSettings
    SearchContentsSummary:
      type: object
      properties:
        query:
          type:
            - string
            - 'null'
          description: >-
            Summarization prompt. Defaults to the search objective / first query
            if omitted.
        schema:
          type:
            - object
            - 'null'
          additionalProperties:
            description: Any type
          description: >-
            Optional JSON Schema (bare). When set, summary is a structured
            object; otherwise a plain string.
        response_format:
          type:
            - object
            - 'null'
          additionalProperties:
            description: Any type
          description: >-
            OpenAI-compatible response_format. Accepts either
            `{type:'json_schema', json_schema:{name, schema, strict?,
            description?}}` (full OpenAI shape) or `{name, schema, strict?,
            description?}` (just the inner json_schema part). When set,
            overrides `json_schema`/`schema`.
      description: Settings for an inline per-result summary.
      title: SearchContentsSummary
    SearchContents:
      type: object
      properties:
        text:
          description: >-
            Bool or { 'max_chars_per_result': N } - when truthy, fetch each
            result page and include the cleaned text.
        highlights:
          description: >-
            Bool or { 'query': str, 'max_chars_per_result': N } - when truthy,
            extract focused highlights from each result page.
        summary:
          oneOf:
            - $ref: '#/components/schemas/SearchContentsSummary'
            - type: 'null'
          description: When set, run an inline per-result summarization call.
      description: Inline second-pass content extraction per result (Exa-style).
      title: SearchContents
    AdvancedSearchSettings:
      type: object
      properties:
        source_policy:
          oneOf:
            - $ref: '#/components/schemas/SearchSourcePolicy'
            - type: 'null'
          description: Domain include/exclude lists and publish-date window.
        excerpt_settings:
          oneOf:
            - $ref: '#/components/schemas/SearchExcerptSettings'
            - type: 'null'
          description: Per-URL excerpt sizing (alias of top-level `max_excerpt_chars`).
        contents:
          oneOf:
            - $ref: '#/components/schemas/SearchContents'
            - type: 'null'
          description: >-
            Inline second-pass content extraction (text / highlights / summary)
            per result.
      description: |-
        Envelope for advanced /v1/search tuning (source policy, excerpt
        settings, inline contents).
      title: AdvancedSearchSettings
    SearchRequestV1:
      type: object
      properties:
        queries:
          type: array
          items:
            type: string
          description: >-
            Keyword search queries to run; their results are merged and
            de-duplicated. Provide 1-5.
        objective:
          type:
            - string
            - 'null'
          description: >-
            Natural-language description of what the caller is looking for. When
            set, results are automatically re-ranked by their relevance to this
            objective using a fast LLM pass - off-topic rows are dropped. Also
            focuses excerpts when
            `advanced_settings.contents.highlights/summary` is requested.
        depth:
          $ref: '#/components/schemas/SearchRequestV1Depth'
          description: >-
            'instant' (~200ms, top of page, no enrichment), 'fast' (~450ms,
            single SERP page), 'auto' (~1s, recommended), 'deep' (~4-18s,
            multi-page gather + merge).
        mode:
          oneOf:
            - $ref: '#/components/schemas/SearchRequestV1Mode'
            - type: 'null'
          description: >-
            Alias of `depth` (basic -> fast, advanced -> auto). If both are
            supplied, `depth` wins.
        category:
          oneOf:
            - $ref: '#/components/schemas/SearchRequestV1Category'
            - type: 'null'
          description: >-
            Result category hint. One of: company, research_paper, news,
            personal_site, financial_report, people.
        limit:
          type: integer
          default: 10
          description: Maximum merged results to return.
        country:
          type: string
          default: us
          description: Two-letter country code to localize results.
        location:
          type:
            - string
            - 'null'
          description: >-
            Alias of `country` (Parallel-style). If both are supplied, `country`
            wins.
        language:
          type: string
          default: en
          description: UI language code.
        freshness:
          oneOf:
            - $ref: '#/components/schemas/SearchRequestV1Freshness'
            - type: 'null'
          description: 'Restrict to recent results: hour, day, week, month or year.'
        include_domains:
          type:
            - array
            - 'null'
          items:
            type: string
          description: Only return results whose URL is on these domains.
        exclude_domains:
          type:
            - array
            - 'null'
          items:
            type: string
          description: Drop results whose URL is on these domains.
        max_excerpt_chars:
          type:
            - integer
            - 'null'
          description: Cap on total excerpt characters across all results.
        session_id:
          type:
            - string
            - 'null'
          description: >-
            Optional caller-supplied session id. Echoed back; if absent a new
            one is generated.
        client_model:
          type:
            - string
            - 'null'
          description: Caller's model identifier. Echoed only; not used.
        advanced_settings:
          oneOf:
            - $ref: '#/components/schemas/AdvancedSearchSettings'
            - type: 'null'
          description: >-
            Envelope for advanced tuning - source policy (include/exclude
            domains, date window), excerpt sizing, and inline second-pass
            content extraction.
        webhook:
          type:
            - string
            - 'null'
          description: >-
            If set, deep-mode (`depth='deep'`) runs POST the finished payload to
            this URL. Ignored for non-deep depths (which return synchronously).
        prompt:
          type:
            - string
            - 'null'
          description: >-
            Research question for the agentic deep-research engine (only applied
            when `depth='deep'`). When absent, the engine falls back to joining
            `queries`.
        max_subqueries:
          type:
            - integer
            - 'null'
          description: Caps the planner's sub-query count (deep only). Default 8.
        max_fetches:
          type:
            - integer
            - 'null'
          description: >-
            Global cap on pages fetched across all sub-queries (deep only).
            Default 18.
      required:
        - queries
      title: SearchRequestV1
    ValidationErrorLocItems:
      oneOf:
        - type: string
        - type: integer
      title: ValidationErrorLocItems
    ValidationErrorCtx:
      type: object
      properties: {}
      title: ValidationErrorCtx
    ValidationError:
      type: object
      properties:
        loc:
          type: array
          items:
            $ref: '#/components/schemas/ValidationErrorLocItems'
        msg:
          type: string
        type:
          type: string
        input:
          description: Any type
        ctx:
          $ref: '#/components/schemas/ValidationErrorCtx'
      required:
        - loc
        - msg
        - type
      title: ValidationError
    HTTPValidationError:
      type: object
      properties:
        detail:
          type: array
          items:
            $ref: '#/components/schemas/ValidationError'
      title: HTTPValidationError
  securitySchemes:
    apiKey:
      type: http
      scheme: bearer
      description: Your API key, sent as a Bearer token.

```

## SDK Code Examples

```python Search_postV1SearchPost_example
import requests

url = "https://core.usescout.sh/v1/search"

payload = {
    "queries": ["climate tech startups 2025", "carbon capture funding"],
    "depth": "fast",
    "limit": 10,
    "country": "us",
    "language": "en",
    "freshness": "month"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())
```

```javascript Search_postV1SearchPost_example
const url = 'https://core.usescout.sh/v1/search';
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{"queries":["climate tech startups 2025","carbon capture funding"],"depth":"fast","limit":10,"country":"us","language":"en","freshness":"month"}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go Search_postV1SearchPost_example
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://core.usescout.sh/v1/search"

	payload := strings.NewReader("{\n  \"queries\": [\n    \"climate tech startups 2025\",\n    \"carbon capture funding\"\n  ],\n  \"depth\": \"fast\",\n  \"limit\": 10,\n  \"country\": \"us\",\n  \"language\": \"en\",\n  \"freshness\": \"month\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby Search_postV1SearchPost_example
require 'uri'
require 'net/http'

url = URI("https://core.usescout.sh/v1/search")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"queries\": [\n    \"climate tech startups 2025\",\n    \"carbon capture funding\"\n  ],\n  \"depth\": \"fast\",\n  \"limit\": 10,\n  \"country\": \"us\",\n  \"language\": \"en\",\n  \"freshness\": \"month\"\n}"

response = http.request(request)
puts response.read_body
```

```java Search_postV1SearchPost_example
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.post("https://core.usescout.sh/v1/search")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"queries\": [\n    \"climate tech startups 2025\",\n    \"carbon capture funding\"\n  ],\n  \"depth\": \"fast\",\n  \"limit\": 10,\n  \"country\": \"us\",\n  \"language\": \"en\",\n  \"freshness\": \"month\"\n}")
  .asString();
```

```php Search_postV1SearchPost_example
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://core.usescout.sh/v1/search', [
  'body' => '{
  "queries": [
    "climate tech startups 2025",
    "carbon capture funding"
  ],
  "depth": "fast",
  "limit": 10,
  "country": "us",
  "language": "en",
  "freshness": "month"
}',
  'headers' => [
    'Authorization' => 'Bearer <token>',
    'Content-Type' => 'application/json',
  ],
]);

echo $response->getBody();
```

```csharp Search_postV1SearchPost_example
using RestSharp;

var client = new RestClient("https://core.usescout.sh/v1/search");
var request = new RestRequest(Method.POST);
request.AddHeader("Authorization", "Bearer <token>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"queries\": [\n    \"climate tech startups 2025\",\n    \"carbon capture funding\"\n  ],\n  \"depth\": \"fast\",\n  \"limit\": 10,\n  \"country\": \"us\",\n  \"language\": \"en\",\n  \"freshness\": \"month\"\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift Search_postV1SearchPost_example
import Foundation

let headers = [
  "Authorization": "Bearer <token>",
  "Content-Type": "application/json"
]
let parameters = [
  "queries": ["climate tech startups 2025", "carbon capture funding"],
  "depth": "fast",
  "limit": 10,
  "country": "us",
  "language": "en",
  "freshness": "month"
] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://core.usescout.sh/v1/search")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```