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

# Search

> Perform a federated web search returning organic results, snippets, and metadata.

## Description

This endpoint performs a Google web search and optionally scrapes the content of the top search results, returning both search results and scraped content.

## Endpoint

```
POST https://app.dumplingai.com/api/v1/search
```

## Headers

* **Content-Type:** `application/json`
* **Authorization:** Bearer `<API_KEY>` (required)

## Request Body

```json theme={null}
{
  "query": "string", // Required. The search query.
  "country": "string", // Optional. Country code for location bias (e.g., "US" for United States).
  "location": "string", // Optional. Specific location to focus the search (e.g., "New York, NY").
  "language": "string", // Optional. Language code for the search results (e.g., "en" for English).
  "dateRange": "string", // Optional. Can be "anyTime", "pastHour", "pastDay", "pastWeek", "pastMonth", or "pastYear".
  "page": "number", // Optional. Page number for paginated results.
  "scrapeResults": "boolean", // Optional. Whether to scrape top search results. Default: false.
  "numResultsToScrape": "number", // Optional. Number of top results to scrape. Default: 3. Max: 10.
  "scrapeOptions": {
    // Optional. Options for scraping, if scrapeResults is true.
    "format": "string", // Optional. The format of the output. Valid values: "markdown", "html", "screenshot". Default: "markdown".
    "cleaned": "boolean" // Optional. Whether the output should be cleaned. Default: true.
  }
}
```

## Responses

### Success (200)

Returns the search results and optionally scraped content.

```json theme={null}
{
  "searchParameters": {
    "q": "string", // The search query
    "type": "string", // e.g., "search"
    "engine": "string", // e.g., "google"
    "gl": "string", // Optional. Google country code
    "hl": "string" // Optional. Host language
  },
  "organic": [
    {
      "title": "string",
      "link": "string",
      "snippet": "string",
      "position": "number",
      "sitelinks": [
        {
          "title": "string",
          "link": "string"
        }
      ],
      "date": "string", // Optional. Publication date if available
      "scrapeOutput": {
        // Optional. Present only if scraping was requested
        "title": "string",
        "metadata": "object",
        "url": "string",
        "format": "string", // "markdown", "html", or "screenshot"
        "cleaned": "boolean",
        "content": "string"
      }
    }
  ],
  "featuredSnippet": {
    "title": "string",
    "link": "string",
    "snippet": "string",
    "position": "number",
    "type": "string"
  },
  "relatedSearches": [
    {
      "query": "string"
    }
  ],
  "peopleAlsoAsk": [
    {
      "question": "string",
      "snippet": "string",
      "title": "string",
      "link": "string"
    }
  ]
}
```

* **Content-Type:** application/json
* **X-RateLimit-Limit:** The rate limit for the user.
* **X-RateLimit-Remaining:** The remaining number of requests for the user.

### Bad Request (400)

Returned if the request is invalid.

```json theme={null}
{
  "error": "Error message describing the issue"
}
```

### Unauthorized (401)

Returned if the API key is invalid or missing.

```json theme={null}
{
  "error": "Invalid or missing Authorization header"
}
```

### Internal Server Error (500)

Returned if there's an error during the search or scraping process.

```json theme={null}
{
  "error": "Failed to perform search: [error message]"
}
```

## Example Request

```bash theme={null}
curl -X POST https://app.dumplingai.com/api/v1/search \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_API_KEY" \
-d '{
  "query": "DumplingAI",
  "country": "US",
  "language": "en",
  "dateRange": "pastMonth",
  "scrapeResults": true,
  "numResultsToScrape": 3,
  "scrapeOptions": {
    "format": "html",
    "cleaned": false
  }
}'
```

## Notes

* The maximum number of results that can be scraped is 10.
* If `numResultsToScrape` is set higher than 10, it will be capped at 10.
* If `numResultsToScrape` is not provided, the default value is 3.
* Credit usage:
  * Base cost for search: 30 credits per page of results
  * Additional credits for scraping are charged normally on the /scrape endpoint.
* If `scrapeResults` is false, no URLs will be scraped and the `scrapeOutput` field will not be present in the organic results.
* The `scrapeOptions` field allows customization of the scraping process:
  * `format` can be "markdown", "html", or "screenshot". If not specified, "markdown" is used.
  * `cleaned` determines whether the output should be cleaned. If not specified, it defaults to true.
* The `dateRange` parameter can be used to filter results by date. Valid values are "anyTime", "pastHour", "pastDay", "pastWeek", "pastMonth", or "pastYear".
* The `country` parameter should be a two-letter country code (e.g., "US" for United States).
* The `location` parameter can be used to focus the search on a specific area. You can find a list of supported locations at GET: `/api/v1/google-locations`
* The `language` parameter can be used to specify the desired language for the search results.
* Usage is recorded with detailed parameters for each request.
* Events may be logged for analytics purposes if enabled.

## Rate Limiting

Rate limit headers (`X-RateLimit-Limit` and `X-RateLimit-Remaining`) are included in the response to indicate the user's current rate limit status.


## OpenAPI

````yaml POST /api/v1/search
openapi: 3.0.3
info:
  title: DumplingAI API
  version: 1.0.0
  description: >
    REST API for DumplingAI's content intelligence and automation platform.

    All endpoints are grouped under `/api/v1`; most are secured via Bearer API
    keys unless an operation explicitly sets `security: []`.
servers:
  - url: https://app.dumplingai.com
    description: Production
security:
  - bearerAuth: []
tags:
  - name: YouTube
    description: Access metadata, search results, and transcripts from YouTube.
  - name: TikTok
    description: Retrieve TikTok profile, video, follower, and transcript data.
  - name: LinkedIn
    description: Programmatically fetch LinkedIn company and profile data.
  - name: Search
    description: Search-orientated endpoints spanning web, news, maps, and autocomplete.
  - name: Google
    description: Integrations with Google business listings and location data.
  - name: Scraping
    description: Webpage capture, crawling, and structured content extraction utilities.
  - name: Documents
    description: Document processing, conversion, and metadata utilities.
  - name: AI
    description: DumplingAI agent and knowledge base endpoints.
  - name: Developer Tools
    description: Utilities for executing sandboxed code via API.
paths:
  /api/v1/search:
    post:
      tags:
        - Search
      summary: Search web content
      description: >-
        Perform a federated web search returning organic results, snippets, and
        metadata.
      operationId: searchWeb
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SearchRequest'
            examples:
              default:
                value:
                  query: best running shoes
                  scrapeResults: true
      responses:
        '200':
          description: Search results returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchResponse'
        '400':
          description: Invalid request payload.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Missing or invalid API key.
        '500':
          description: Unexpected server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    SearchRequest:
      type: object
      required:
        - query
      properties:
        query:
          type: string
        country:
          type: string
          description: 2-letter country code forwarded as `gl`.
        location:
          type: string
          description: Free-form location context forwarded to the provider.
        language:
          type: string
          description: Interface language forwarded as `hl`.
        dateRange:
          type: string
          description: Temporal filter applied to the search results.
          enum:
            - pastHour
            - pastDay
            - pastWeek
            - pastMonth
            - pastYear
            - anyTime
        page:
          type: integer
          minimum: 1
        scrapeResults:
          type: boolean
          default: false
          description: >-
            When true, the service will scrape top organic results for rich
            content.
        numResultsToScrape:
          type: integer
          minimum: 1
          maximum: 10
          default: 3
        scrapeOptions:
          type: object
          properties:
            format:
              type: string
              enum:
                - markdown
                - html
                - screenshot
            cleaned:
              type: boolean
          additionalProperties: false
        requestSource:
          $ref: '#/components/schemas/RequestSource'
      additionalProperties: false
    SearchResponse:
      type: object
      properties:
        searchParameters:
          type: object
          properties:
            q:
              type: string
            type:
              type: string
            engine:
              type: string
            gl:
              type: string
              nullable: true
            hl:
              type: string
              nullable: true
          required:
            - q
            - type
            - engine
          additionalProperties: true
        organic:
          type: array
          items:
            $ref: '#/components/schemas/SearchOrganicResult'
        featuredSnippet:
          $ref: '#/components/schemas/SearchFeaturedSnippet'
        relatedSearches:
          type: array
          items:
            type: object
            properties:
              query:
                type: string
            required:
              - query
            additionalProperties: false
        peopleAlsoAsk:
          type: array
          items:
            $ref: '#/components/schemas/SearchPeopleAlsoAsk'
      required:
        - searchParameters
        - organic
      additionalProperties: true
    ErrorResponse:
      type: object
      properties:
        error:
          type: string
          description: Human-readable description of what went wrong.
      required:
        - error
    RequestSource:
      type: string
      description: Optional identifier describing where the API request originated.
      enum:
        - API
        - WEB
        - MAKE_DOT_COM
        - ZAPIER
        - N8N
        - PLAYGROUND
        - DEFAULT_AUTOMATION
        - AGENT_PREVIEW
        - AGENT_LIVE
        - AUTOPILOT
        - STUDIO
    SearchOrganicResult:
      type: object
      properties:
        title:
          type: string
        link:
          type: string
          format: uri
        snippet:
          type: string
        position:
          type: integer
        sitelinks:
          type: array
          items:
            type: object
            properties:
              title:
                type: string
              link:
                type: string
                format: uri
            required:
              - title
              - link
            additionalProperties: false
        date:
          type: string
          nullable: true
        scrapeOutput:
          $ref: '#/components/schemas/SearchScrapeOutput'
      required:
        - title
        - link
        - snippet
        - position
      additionalProperties: true
    SearchFeaturedSnippet:
      type: object
      properties:
        title:
          type: string
        link:
          type: string
          format: uri
        snippet:
          type: string
        position:
          type: integer
        type:
          type: string
      required:
        - title
        - link
        - snippet
        - position
        - type
      additionalProperties: true
    SearchPeopleAlsoAsk:
      type: object
      properties:
        question:
          type: string
        snippet:
          type: string
        title:
          type: string
        link:
          type: string
          format: uri
      required:
        - question
        - snippet
        - title
        - link
      additionalProperties: true
    SearchScrapeOutput:
      type: object
      properties:
        title:
          type: string
        metadata:
          type: object
          additionalProperties: true
        url:
          type: string
          format: uri
        format:
          type: string
        cleaned:
          type: boolean
        content:
          type: string
      additionalProperties: true
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key

````