Serper Webpage Scrape API

openapi: 3.0.3
info:
  title: Serper Webpage Scrape API
  description: >-
    Serper's webpage scraping surface. A single POST to the host root returns the
    extracted contents of a URL, optionally as markdown and with images, links and
    videos included. Serper's own playground states that most webpages cost 2 credits,
    with harder-to-scrape pages costing 6 or 10 credits depending on difficulty, and
    that the number of credits consumed is returned in the response body.
  version: 1.0.0
  contact:
    name: Serper Support
    url: https://serper.dev
    email: support@serper.dev
  termsOfService: https://serper.dev/terms
  license:
    name: Commercial
    url: https://serper.dev
  x-provenance:
    method: derived
    generated: '2026-08-13'
    source: >-
      https://serper.dev/_next/static/chunks/pages/playground-7ce8960e9fe2fc99.js —
      Serper's own first-party playground bundle, which routes type "webpage" to
      https://scrape.serper.dev and builds the request body
      {url, includeMarkdown, includeImages, includeLinks, includeVideos}.
    note: >-
      Request shape is taken verbatim from Serper's published client code. Serper
      publishes no OpenAPI, and the response schema is not described in the client
      bundle, so the 200 response is left as a free-form object rather than invented.

servers:
  - url: https://scrape.serper.dev
    description: Serper webpage scrape host

security:
  - apiKeyHeader: []

tags:
  - name: Scrape
    description: Webpage content extraction

paths:
  /:
    post:
      operationId: scrapeWebpage
      summary: Scrape a webpage
      description: >-
        Fetch and extract the contents of a single URL. Optional flags control whether
        markdown, images, links and videos are included in the response.
      tags:
        - Scrape
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ScrapeRequest'
            example:
              url: https://apievangelist.com
              includeMarkdown: true
      responses:
        '200':
          description: >-
            Extracted page contents. Serper does not publish a response schema for this
            endpoint; the playground renders a MARKDOWN tab when `markdown` is present,
            and the credits consumed are returned in the response.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '400':
          $ref: '#/components/responses/BadRequest'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'

components:
  schemas:
    ScrapeRequest:
      type: object
      required:
        - url
      properties:
        url:
          type: string
          format: uri
          description: The URL of the webpage to scrape.
        includeMarkdown:
          type: boolean
          description: Include a markdown rendering of the page contents.
        includeImages:
          type: boolean
          description: Include images extracted from the page.
        includeLinks:
          type: boolean
          description: Include links extracted from the page.
        includeVideos:
          type: boolean
          description: Include videos extracted from the page.
    ErrorResponse:
      type: object
      properties:
        message:
          type: string
          description: Human-readable error description.
        statusCode:
          type: integer
          description: HTTP status code, repeated in the body.
        error:
          type: string
          description: Short error label, present on some responses.
  responses:
    BadRequest:
      description: Bad request — missing or invalid parameters.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Forbidden:
      description: >-
        Forbidden — missing or invalid API key. Observed body on an unauthenticated
        request: {"message":"Unauthorized. Sign up for a free account.","statusCode":403}
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    TooManyRequests:
      description: Too many requests — rate limit exceeded or credits exhausted.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  securitySchemes:
    apiKeyHeader:
      type: apiKey
      in: header
      name: X-API-KEY
      description: API key obtained from https://serper.dev/api-keys