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

# Scrape Markdown

> Convert any page into clean Markdown optimized for agents, RAG, search, and analysis.

<Badge color="blue">1 Credit</Badge> <Badge color="orange">With actions: 2 Credits</Badge>


## OpenAPI

````yaml GET /web/scrape/markdown
openapi: 3.1.0
info:
  title: Context API
  description: API for retrieving context data from any website
  version: 1.0.0
servers:
  - url: https://api.context.dev/v1
security: []
tags:
  - name: Batch
    description: Scrape many pages or crawl a site asynchronously.
  - name: Monitors
    description: >-
      Monitor pages, sitemaps, and extracted website data for exact or semantic
      changes. Webhook payloads are documented by the
      MonitorsChangeDetectedWebhookPayload and
      MonitorsRunCompletedWebhookPayload schemas.
  - name: WebDBs
    description: Create structured tables from web pages and keep them up to date.
  - name: News
    description: >-
      Search live first-party RSS and free historical news data by company
      identity.
paths:
  /web/scrape/markdown:
    get:
      tags:
        - Web Scraping
      summary: Scrape Markdown
      description: >-
        Scrapes the given URL into LLM usable Markdown. Inspect key_metadata on
        JSON responses from a recognized API key; use error_code to distinguish
        stable failure categories.


        ### YouTube


        YouTube URLs return the video or channel itself rather than the
        surrounding player and navigation chrome. A URL addressing a single
        video (`/watch`, `youtu.be`, `/shorts`, `/embed`, `/live`) returns its
        title, channel, duration, view count, keywords, full description, and
        the transcript when the video has captions that can be retrieved; videos
        without captions return everything except the transcript. A channel URL
        (`/channel/UC…`, `/@handle`, `/c/…`, `/user/…`) returns its name,
        handle, subscriber count, video count, and full description. When
        `includeImages=true`, video responses also include the thumbnail and
        channel responses include the avatar. Costs the same as any other
        scrape.


        ### Billing & errors


        | HTTP status | Billed? | Meaning |

        | --- | --- | --- |

        | 200 | Yes — 1 credit, or 2 credits with actions | Successful scrape,
        including a zero-length result when includeSelectors matched nothing |

        | 400 | No | Invalid input, skipped PDF, or the page could not be
        scraped. error_code WEBSITE_BLOCKED specifically means the site answered
        with an anti-bot challenge, CAPTCHA wall, or login shell instead of the
        page (even when the site returned HTTP 200) — retrying later or from
        another country sometimes succeeds |

        | 401 / 403 | No | Invalid/disabled key, insufficient permissions, or
        credits exhausted; inspect error_code |

        | 404 | No | Target page returned or fingerprinted as not found |

        | 408 | No | Request timed out |

        | 413 | No | Target content exceeds the maximum supported size (20 MB) |

        | 415 | No | Unsupported content type |

        | 429 | No | Per-minute rate limit exceeded; honor Retry-After |

        | 500 | No | Internal error |
      parameters:
        - schema:
            type: string
            minLength: 1
            format: uri
            description: >-
              Full URL to scrape into LLM usable Markdown (must include http://
              or https:// protocol)
          required: true
          description: >-
            Full URL to scrape into LLM usable Markdown (must include http:// or
            https:// protocol)
          name: url
          in: query
        - schema:
            type: boolean
            default: true
            description: Preserve hyperlinks in Markdown output
          required: false
          description: Preserve hyperlinks in Markdown output
          name: includeLinks
          in: query
        - schema:
            type: boolean
            default: false
            description: Include image references in Markdown output
          required: false
          description: Include image references in Markdown output
          name: includeImages
          in: query
        - schema:
            type: boolean
            default: true
            description: Shorten base64-encoded image data in the Markdown output
          required: false
          description: Shorten base64-encoded image data in the Markdown output
          name: shortenBase64Images
          in: query
        - schema:
            type: boolean
            default: false
            description: >-
              Extract only the main content of the page, excluding headers,
              footers, sidebars, and navigation
          required: false
          description: >-
            Extract only the main content of the page, excluding headers,
            footers, sidebars, and navigation
          name: useMainContentOnly
          in: query
        - schema:
            type: boolean
            default: false
            description: >-
              When true, the response also includes an `html` field with the
              page HTML the Markdown was converted from — the same body the
              Scrape HTML endpoint returns for the equivalent request.
          required: false
          description: >-
            When true, the response also includes an `html` field with the page
            HTML the Markdown was converted from — the same body the Scrape HTML
            endpoint returns for the equivalent request.
          name: includeHTML
          in: query
        - schema:
            type: object
            properties:
              shouldParse:
                type: boolean
                default: true
                description: >-
                  When true, PDF URLs are fetched and parsed. When false, PDF
                  URLs are skipped and a 400 PDF_SKIPPED is returned.
              start:
                type: integer
                minimum: 1
                description: >-
                  First 1-based PDF page to parse. When omitted, parsing starts
                  at the first page.
              end:
                type: integer
                minimum: 1
                description: >-
                  Last 1-based PDF page to parse. When omitted, parsing ends at
                  the last page. Must be greater than or equal to start when
                  both are provided.
              ocr:
                type: boolean
                default: false
                description: >-
                  When true, OCR the selected PDF pages that have no usable text
                  layer (scans), replacing each recovered page's text with the
                  OCR result while pages with a real text layer keep it. Billed
                  at 1 credit per page OCR actually recovered, on top of the
                  base request cost. When false, no OCR runs.
            default:
              shouldParse: true
              ocr: false
            description: >-
              PDF parsing controls. Use start/end to limit text extraction and
              embedded-image detection/OCR to an inclusive 1-based page range.
          required: false
          description: >-
            PDF parsing controls. Use start/end to limit text extraction and
            embedded-image detection/OCR to an inclusive 1-based page range.
          name: pdf
          in: query
        - schema:
            type: boolean
            default: false
            description: When true, the contents of iframes are rendered to Markdown.
          required: false
          description: When true, the contents of iframes are rendered to Markdown.
          name: includeFrames
          in: query
        - schema:
            type:
              - array
              - 'null'
            items:
              type: string
              minLength: 1
              maxLength: 2048
            maxItems: 50
            description: >-
              CSS selectors. When provided, only matching HTML subtrees (and
              their descendants) are kept before conversion to Markdown. When
              omitted, the entire document is kept. Examples: "article.main",
              "#content", "[role=main]".
          required: false
          description: >-
            CSS selectors. When provided, only matching HTML subtrees (and their
            descendants) are kept before conversion to Markdown. When omitted,
            the entire document is kept. Examples: "article.main", "#content",
            "[role=main]".
          name: includeSelectors
          in: query
        - schema:
            type:
              - array
              - 'null'
            items:
              type: string
              minLength: 1
              maxLength: 2048
            maxItems: 50
            description: >-
              CSS selectors to remove before conversion to Markdown. Applied
              after includeSelectors. Exclusion takes precedence: an element
              matching both is removed. Examples: "nav", "footer", ".ad-banner",
              "[aria-hidden=true]".
          required: false
          description: >-
            CSS selectors to remove before conversion to Markdown. Applied after
            includeSelectors. Exclusion takes precedence: an element matching
            both is removed. Examples: "nav", "footer", ".ad-banner",
            "[aria-hidden=true]".
          name: excludeSelectors
          in: query
        - schema:
            type:
              - integer
              - 'null'
            minimum: 0
            maximum: 2592000000
            default: 86400000
            description: >-
              Return a cached result if a prior scrape for the same parameters
              exists and is younger than this many milliseconds. Defaults to 1
              day (86400000 ms) when omitted. Max is 30 days (2592000000 ms).
              Set to 0 to always scrape fresh.
          required: false
          description: >-
            Return a cached result if a prior scrape for the same parameters
            exists and is younger than this many milliseconds. Defaults to 1 day
            (86400000 ms) when omitted. Max is 30 days (2592000000 ms). Set to 0
            to always scrape fresh.
          name: maxAgeMs
          in: query
        - schema:
            type:
              - integer
              - 'null'
            minimum: 0
            maximum: 30000
            description: >-
              Optional browser wait time in milliseconds after initial page load
              before converting the page to Markdown. Min: 0. Max: 30000 (30
              seconds).
          required: false
          description: >-
            Optional browser wait time in milliseconds after initial page load
            before converting the page to Markdown. Min: 0. Max: 30000 (30
            seconds).
          name: waitForMs
          in: query
        - schema:
            type: boolean
            default: false
            description: >-
              When true, waits briefly for CSS and transition animations to
              settle before converting to Markdown. Defaults to false. This adds
              a bit of latency in exchange for more stable output on animated
              pages.
          required: false
          description: >-
            When true, waits briefly for CSS and transition animations to settle
            before converting to Markdown. Defaults to false. This adds a bit of
            latency in exchange for more stable output on animated pages.
          name: settleAnimations
          in: query
        - schema:
            type:
              - array
              - 'null'
            items:
              $ref: '#/components/schemas/WebScrapeAction'
            maxItems: 5
            description: >-
              Optional browser actions executed in array order after the page
              loads and before content is captured. Requires a paid plan. Send a
              JSON array in the query parameter. Maximum: 5 actions.
          required: false
          description: >-
            Optional browser actions executed in array order after the page
            loads and before content is captured. Requires a paid plan. Send a
            JSON array in the query parameter. Maximum: 5 actions.
          name: actions
          in: query
        - schema:
            type: object
            additionalProperties:
              type: string
              maxLength: 8192
              pattern: ^[^\r\n]*$
            description: >-
              Optional outbound HTTP headers forwarded only to the target URL,
              sent as deep-object query params such as headers[X-Custom]=value.
              When provided, caching is bypassed: the result is neither read
              from nor written to cache.
          required: false
          description: >-
            Optional outbound HTTP headers forwarded only to the target URL,
            sent as deep-object query params such as headers[X-Custom]=value.
            When provided, caching is bypassed: the result is neither read from
            nor written to cache.
          name: headers
          in: query
        - schema:
            $ref: '#/components/schemas/BrowserCountryCode'
          required: false
          description: >-
            Fetch the target page through a residential proxy in this country
            (ISO 3166-1 alpha-2).
          name: country
          in: query
        - schema:
            $ref: '#/components/schemas/LenientTimeoutMS'
          required: false
          description: >-
            Optional timeout in milliseconds for the request. If the request
            takes longer than this value, it will be aborted with a 408 status
            code. Maximum allowed value is 300000ms (5 minutes).
          name: timeoutMS
          in: query
        - schema:
            type: string
            enum:
              - enabled
              - disabled
            default: disabled
            description: >-
              Set to enabled to bypass shared caches and omit request and
              response content from retained usage logs. Requires zero data
              retention to be enabled for your organization (contact
              support@context.dev), otherwise the request fails with
              ZDR_NOT_ENABLED. Successful ZDR responses include X-Context-ZDR:
              true.
          required: false
          description: >-
            Set to enabled to bypass shared caches and omit request and response
            content from retained usage logs. Requires zero data retention to be
            enabled for your organization (contact support@context.dev),
            otherwise the request fails with ZDR_NOT_ENABLED. Successful ZDR
            responses include X-Context-ZDR: true.
          name: zdr
          in: query
        - $ref: '#/components/parameters/RequestTags'
      responses:
        '200':
          description: Successful response
          headers:
            X-RateLimit-Limit:
              $ref: '#/components/headers/RateLimitLimit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/RateLimitRemaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/RateLimitReset'
            X-Context-ZDR:
              description: >-
                Present with the value true when zero data retention was
                requested and honored.
              schema:
                type: string
                enum:
                  - 'true'
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    enum:
                      - true
                    description: Indicates success
                  markdown:
                    type: string
                    description: Page content converted to GitHub Flavored Markdown
                  html:
                    type: string
                    description: >-
                      Only present when includeHTML=true: the page HTML the
                      Markdown was converted from — the same body the Scrape
                      HTML endpoint returns for the equivalent request.
                  contentLength:
                    type: integer
                    minimum: 0
                    description: >-
                      UTF-8 byte length of the returned Markdown. Use 0 to
                      identify an empty result and compare small values against
                      your workload's minimum useful-content threshold.
                  url:
                    type: string
                    description: The URL that was scraped
                  metadata:
                    $ref: '#/components/schemas/PageMetadata'
                  cache_metadata:
                    $ref: '#/components/schemas/CacheMetadata'
                  key_metadata:
                    $ref: '#/components/schemas/KeyMetadata'
                  actionsApplied:
                    type: array
                    description: >-
                      One verified outcome per requested browser action, in
                      request order.
                    items:
                      type: object
                      properties:
                        instruction:
                          type: string
                        status:
                          type: string
                          enum:
                            - applied
                            - failed
                            - skipped
                          description: >-
                            Applied means the requested page state was visibly
                            verified. Failed means it was not verified. Skipped
                            means it was not attempted.
                        method:
                          type: string
                        targetDescription:
                          type: string
                        completionEvidence:
                          type: string
                          description: >-
                            Visible page evidence used to verify an applied
                            action.
                        error:
                          type: string
                        durationMs:
                          type: number
                      required:
                        - instruction
                        - status
                  actionsHtmlStale:
                    type: boolean
                    description: >-
                      True when an action was applied but the returned content
                      could not be refreshed afterward.
                required:
                  - success
                  - markdown
                  - contentLength
                  - url
                  - metadata
                  - cache_metadata
        '400':
          description: Bad request - Invalid URL or failed to scrape
          headers:
            X-RateLimit-Limit:
              $ref: '#/components/headers/RateLimitLimit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/RateLimitRemaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/RateLimitReset'
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: Error message describing the issue
                  error_code:
                    type: string
                    enum:
                      - INPUT_VALIDATION_ERROR
                      - WEBSITE_ACCESS_ERROR
                      - WEBSITE_BLOCKED
                    description: >-
                      Error code indicating the type of error. WEBSITE_BLOCKED
                      means the site answered with an anti-bot challenge,
                      CAPTCHA wall, or login shell instead of the page (often as
                      an HTTP 200) — the request is not billed, and retrying
                      later or from another country sometimes succeeds.
                  key_metadata:
                    $ref: '#/components/schemas/KeyMetadata'
                required:
                  - message
                  - error_code
        '401':
          description: Unauthorized - Invalid or missing API key
          headers:
            X-RateLimit-Limit:
              $ref: '#/components/headers/RateLimitLimit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/RateLimitRemaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/RateLimitReset'
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: Error message
                  error_code:
                    type: string
                    enum:
                      - UNAUTHORIZED
                    description: Error code indicating unauthorized access
                  key_metadata:
                    $ref: '#/components/schemas/KeyMetadata'
        '403':
          description: Forbidden - Insufficient permissions or usage limit exceeded
          headers:
            X-RateLimit-Limit:
              $ref: '#/components/headers/RateLimitLimit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/RateLimitRemaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/RateLimitReset'
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: Error message
                  error_code:
                    type: string
                    enum:
                      - FORBIDDEN
                      - USAGE_EXCEEDED
                      - DISABLED
                      - INSUFFICIENT_PERMISSIONS
                    description: Error code indicating forbidden access
                  key_metadata:
                    $ref: '#/components/schemas/KeyMetadata'
        '404':
          description: Target page returned a 404
          headers:
            X-RateLimit-Limit:
              $ref: '#/components/headers/RateLimitLimit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/RateLimitRemaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/RateLimitReset'
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: Error message describing the issue
                  error_code:
                    type: string
                    enum:
                      - NOT_FOUND
                    description: Error code indicating the target page was not found
                  key_metadata:
                    $ref: '#/components/schemas/KeyMetadata'
                required:
                  - message
                  - error_code
        '408':
          description: Request timeout
          headers:
            X-RateLimit-Limit:
              $ref: '#/components/headers/RateLimitLimit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/RateLimitRemaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/RateLimitReset'
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: Timeout error message
                  error_code:
                    type: string
                    enum:
                      - REQUEST_TIMEOUT
                    description: Error code indicating request timeout
                  key_metadata:
                    $ref: '#/components/schemas/KeyMetadata'
        '413':
          description: >-
            Content too large - the target content exceeds the maximum supported
            download size, so it cannot be scraped
          headers:
            X-RateLimit-Limit:
              $ref: '#/components/headers/RateLimitLimit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/RateLimitRemaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/RateLimitReset'
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: >-
                      Error message naming the URL and the maximum supported
                      size
                  error_code:
                    type: string
                    enum:
                      - CONTENT_TOO_LARGE
                    description: >-
                      Error code indicating the target content exceeds the
                      maximum supported size
                  key_metadata:
                    $ref: '#/components/schemas/KeyMetadata'
                required:
                  - message
                  - error_code
        '415':
          description: >-
            Unsupported content type - the URL resolved to a content type that
            is not supported (e.g. an image, presentation, media, or archive).
            Supported types are HTML, XML, PDF, DOCX, DOC, XLSX, XLS, PPTX, PPT,
            and CSV.
          headers:
            X-RateLimit-Limit:
              $ref: '#/components/headers/RateLimitLimit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/RateLimitRemaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/RateLimitReset'
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: Error message describing the unsupported content type
                  error_code:
                    type: string
                    enum:
                      - UNSUPPORTED_CONTENT
                    description: Error code indicating an unsupported content type
                  key_metadata:
                    $ref: '#/components/schemas/KeyMetadata'
                required:
                  - message
                  - error_code
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          description: Internal server error
          headers:
            X-RateLimit-Limit:
              $ref: '#/components/headers/RateLimitLimit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/RateLimitRemaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/RateLimitReset'
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: Error message
                  error_code:
                    type: string
                    enum:
                      - INTERNAL_ERROR
                    description: Error code indicating internal server error
                  key_metadata:
                    $ref: '#/components/schemas/KeyMetadata'
      security:
        - bearerAuth: []
      x-codeSamples:
        - lang: JavaScript
          source: >-
            import ContextDev from 'context.dev';


            const client = new ContextDev({
              apiKey: process.env['CONTEXT_DEV_API_KEY'], // This is the default and can be omitted
            });


            const response = await client.web.webScrapeMd({ url:
            'https://example.com' });


            console.log(response.cache_metadata);
        - lang: Python
          source: |-
            import os
            from context.dev import ContextDev

            client = ContextDev(
                api_key=os.environ.get("CONTEXT_DEV_API_KEY"),  # This is the default and can be omitted
            )
            response = client.web.web_scrape_md(
                url="https://example.com",
            )
            print(response.cache_metadata)
        - lang: Go
          source: "package main\n\nimport (\n\t\"context\"\n\t\"fmt\"\n\n\t\"github.com/context-dot-dev/context-go-sdk\"\n\t\"github.com/context-dot-dev/context-go-sdk/option\"\n)\n\nfunc main() {\n\tclient := contextdev.NewClient(\n\t\toption.WithAPIKey(\"My API Key\"),\n\t)\n\tresponse, err := client.Web.WebScrapeMd(context.TODO(), contextdev.WebWebScrapeMdParams{\n\t\tURL: \"https://example.com\",\n\t})\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf(\"%+v\\n\", response.CacheMetadata)\n}\n"
        - lang: Ruby
          source: |-
            require "context_dev"

            context_dev = ContextDev::Client.new(api_key: "My API Key")

            response = context_dev.web.web_scrape_md(url: "https://example.com")

            puts(response)
        - lang: PHP
          source: >-
            <?php


            require_once dirname(__DIR__) . '/vendor/autoload.php';


            use ContextDev\Client;

            use ContextDev\Core\Exceptions\APIException;


            $client = new Client(apiKey: getenv('CONTEXT_DEV_API_KEY') ?: 'My
            API Key');


            try {
              $response = $client->web->webScrapeMd(
                url: 'https://example.com',
                actions: [['do' => 'wait', 'timeMs' => 0]],
                country: 'de',
                excludeSelectors: ['x'],
                headers: ['foo' => 'J!'],
                includeFrames: true,
                includeHTML: true,
                includeImages: true,
                includeLinks: true,
                includeSelectors: ['x'],
                maxAgeMs: 0,
                pdf: ['end' => 1, 'ocr' => true, 'shouldParse' => true, 'start' => 1],
                settleAnimations: true,
                shortenBase64Images: true,
                tags: ['production', 'team-alpha'],
                timeoutMs: 1,
                useMainContentOnly: true,
                waitForMs: 0,
                zdr: 'enabled',
              );

              var_dump($response);
            } catch (APIException $e) {
              echo $e->getMessage();
            }
        - lang: CLI
          source: |-
            context-dev web web-scrape-md \
              --api-key 'My API Key' \
              --url https://example.com
components:
  schemas:
    WebScrapeAction:
      oneOf:
        - $ref: '#/components/schemas/WebScrapeWaitAction'
        - $ref: '#/components/schemas/WebScrapePerformAction'
        - $ref: '#/components/schemas/WebScrapeScrollAction'
      discriminator:
        propertyName: do
        mapping:
          wait:
            $ref: '#/components/schemas/WebScrapeWaitAction'
          perform:
            $ref: '#/components/schemas/WebScrapePerformAction'
          scroll:
            $ref: '#/components/schemas/WebScrapeScrollAction'
      description: >-
        Browser action discriminated by `do`. Each variant exposes only its
        applicable fields.
    BrowserCountryCode:
      type: string
      enum:
        - ad
        - ae
        - af
        - ag
        - ai
        - al
        - am
        - ao
        - ar
        - at
        - au
        - aw
        - az
        - ba
        - bb
        - bd
        - be
        - bf
        - bg
        - bh
        - bi
        - bj
        - bm
        - bn
        - bo
        - bq
        - br
        - bs
        - bw
        - by
        - bz
        - ca
        - cd
        - cf
        - cg
        - ch
        - ci
        - cl
        - cm
        - cn
        - co
        - cr
        - cv
        - cw
        - cy
        - cz
        - de
        - dj
        - dk
        - dm
        - do
        - dz
        - ec
        - ee
        - eg
        - es
        - et
        - fi
        - fj
        - fr
        - ga
        - gb
        - gd
        - ge
        - gf
        - gg
        - gh
        - gm
        - gn
        - gp
        - gq
        - gr
        - gt
        - gu
        - gw
        - gy
        - hk
        - hn
        - hr
        - ht
        - hu
        - id
        - ie
        - il
        - im
        - in
        - iq
        - ir
        - is
        - it
        - je
        - jm
        - jo
        - jp
        - ke
        - kg
        - kh
        - kn
        - kr
        - kw
        - ky
        - kz
        - la
        - lb
        - lc
        - lk
        - lr
        - ls
        - lt
        - lu
        - lv
        - ly
        - ma
        - mc
        - md
        - me
        - mf
        - mg
        - mk
        - ml
        - mm
        - mn
        - mo
        - mq
        - mr
        - mt
        - mu
        - mv
        - mw
        - mx
        - my
        - mz
        - na
        - nc
        - ne
        - ng
        - ni
        - nl
        - 'no'
        - np
        - nz
        - om
        - pa
        - pe
        - pf
        - pg
        - ph
        - pk
        - pl
        - pr
        - ps
        - pt
        - py
        - qa
        - re
        - ro
        - rs
        - ru
        - rw
        - sa
        - sc
        - sd
        - se
        - sg
        - si
        - sk
        - sl
        - sm
        - sn
        - so
        - sr
        - ss
        - st
        - sv
        - sx
        - sy
        - sz
        - tc
        - td
        - tg
        - th
        - tj
        - tl
        - tm
        - tn
        - tr
        - tt
        - tw
        - tz
        - ua
        - ug
        - us
        - uy
        - uz
        - vc
        - ve
        - vg
        - vi
        - vn
        - ye
        - yt
        - za
        - zm
        - zw
      example: de
      description: >-
        Fetch the target page through a residential proxy in this country (ISO
        3166-1 alpha-2).
    LenientTimeoutMS:
      type: integer
      minimum: 1
      maximum: 300000
      description: >-
        Optional timeout in milliseconds for the request. If the request takes
        longer than this value, it will be aborted with a 408 status code.
        Maximum allowed value is 300000ms (5 minutes).
    PageMetadata:
      type: object
      properties:
        sourceUrl:
          type: string
          description: Original URL requested by the caller.
        finalUrl:
          type: string
          description: >-
            Final URL scraped after redirects or scraper fallback, when known.
            Falls back to sourceUrl when unavailable.
        title:
          type: string
          description: Best title extracted from the page.
        description:
          type: string
          description: >-
            Best description extracted from standard, Open Graph, or Twitter
            metadata.
        language:
          type: string
          description: Language extracted from html lang or language meta tags.
        keywords:
          type: array
          items:
            type: string
          description: Keywords extracted from the page's keywords meta tag.
        canonicalUrl:
          type: string
          description: Resolved canonical URL, when present.
        author:
          type: string
          description: Author metadata, when present.
        siteName:
          type: string
          description: Site or application name from page metadata.
        image:
          type: string
          description: >-
            Primary resolved preview image from Open Graph, Twitter, or image
            metadata.
        favicon:
          type: string
          description: Resolved favicon URL, when present.
        publishedTime:
          type: string
          description: Published timestamp/date from page metadata, when present.
        modifiedTime:
          type: string
          description: Modified timestamp/date from page metadata, when present.
        robots:
          type: string
          description: Robots meta directive, when present.
        openGraph:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/PageMetadataValue'
          description: >-
            Open Graph metadata with the og: prefix removed and keys
            camel-cased.
        twitter:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/PageMetadataValue'
          description: >-
            Twitter card metadata with the twitter: prefix removed and keys
            camel-cased.
        alternates:
          type: array
          items:
            $ref: '#/components/schemas/PageMetadataAlternate'
          description: Resolved alternate links from link rel=alternate tags.
        headings:
          type: array
          items:
            $ref: '#/components/schemas/PageMetadataHeading'
          description: >-
            Page headings (h1–h6) in document order, extracted from the
            unfiltered document. Capped at the first 500 headings. Omitted when
            the page has none.
        jsonLd:
          type: array
          items:
            type: object
            additionalProperties: true
          description: JSON-LD structured data blocks parsed from the page.
        additionalMeta:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/PageMetadataValue'
          description: >-
            Additional non-social meta tags not promoted to top-level metadata
            fields.
      required:
        - sourceUrl
        - finalUrl
      description: Metadata extracted from the scraped page HTML.
    CacheMetadata:
      type: object
      properties:
        status:
          type: string
          enum:
            - hit
            - miss
            - zdr
          description: >-
            Whether the response was served from cache, required fresh work, or
            honored zero-data-retention cache bypass.
        age_ms:
          type: integer
          minimum: 0
          description: >-
            Age of the cached data in milliseconds. Zero for miss and zdr
            responses.
      required:
        - status
        - age_ms
      additionalProperties: false
      description: >-
        Cache outcome for this response. Composite responses are hits only when
        every cache-controlled fetch contributing to the output was a hit;
        age_ms is the oldest contributing hit.
    KeyMetadata:
      type: object
      properties:
        credits_consumed:
          type: integer
          description: The number of credits consumed by this request.
        credits_remaining:
          type: integer
          description: >-
            The number of credits remaining for your organization after this
            request.
      required:
        - credits_consumed
        - credits_remaining
      description: >-
        Metadata about the API key used for the request. Included in every
        response whenever a valid API key is provided, even when the response
        status is not 200.
    WebScrapeWaitAction:
      type: object
      properties:
        do:
          type: string
          enum:
            - wait
        timeMs:
          type: integer
          minimum: 0
          maximum: 30000
      required:
        - do
        - timeMs
      additionalProperties: false
      description: >-
        Pause for a fixed number of milliseconds before continuing to the next
        action.
      title: Wait
    WebScrapePerformAction:
      type: object
      properties:
        do:
          type: string
          enum:
            - perform
        action:
          type: string
          minLength: 1
          maxLength: 500
      required:
        - do
        - action
      additionalProperties: false
      description: Resolve and perform one natural-language browser action.
      title: Perform
    WebScrapeScrollAction:
      type: object
      properties:
        do:
          type: string
          enum:
            - scroll
        direction:
          type: string
          enum:
            - up
            - down
            - left
            - right
          description: Direction to scroll. Defaults to down.
        amount:
          anyOf:
            - type: integer
              minimum: 1
              maximum: 100000
            - type: string
              enum:
                - viewport
                - max
          description: >-
            Pixels per scroll, one visible viewport, or the current scroll
            boundary. Defaults to viewport.
        container:
          type: string
          minLength: 1
          maxLength: 2000
          description: >-
            CSS selector for the first matching scroll container. Defaults to
            the page.
        maxScrolls:
          type: integer
          minimum: 1
          maximum: 50
          description: >-
            Maximum scroll iterations. Stops early when scrolling and scrollable
            extent stop changing. Defaults to 1.
      required:
        - do
      additionalProperties: false
      description: >-
        Scroll the page or a selected scrollable container, waiting adaptively
        for content and dimensions to settle after each iteration.
      title: Scroll
    RequestTags:
      type: array
      items:
        type: string
        minLength: 1
        maxLength: 50
      maxItems: 20
      description: >-
        Optional tags for tracking usage. Up to 20 tags, each 1 to 50
        characters.
      example:
        - production
        - team-alpha
    PageMetadataValue:
      oneOf:
        - type: string
        - type: array
          items:
            type: string
    PageMetadataAlternate:
      type: object
      properties:
        href:
          type: string
          description: Resolved alternate URL.
        hreflang:
          type: string
          description: Language or locale for the alternate URL, when present.
        type:
          type: string
          description: Alternate resource MIME type, when present.
        title:
          type: string
          description: Alternate resource title, when present.
      required:
        - href
      additionalProperties: false
    PageMetadataHeading:
      type: object
      properties:
        level:
          type: integer
          minimum: 1
          maximum: 6
          description: Heading level, 1–6 (from h1–h6).
        text:
          type: string
          description: >-
            Heading text with whitespace collapsed, truncated to 1000
            characters.
      required:
        - level
        - text
      additionalProperties: false
  parameters:
    RequestTags:
      name: tags
      in: query
      required: false
      style: form
      explode: false
      schema:
        $ref: '#/components/schemas/RequestTags'
      description: >-
        Optional comma-separated caller-defined tags for tracking this request.
        Tags are recorded on the request's usage log and can be used to filter
        usage on the dashboard usage page. Up to 20 tags, each 1-50 characters.
      example: production,team-alpha
  headers:
    RateLimitLimit:
      description: >-
        Maximum requests allowed in the current fixed one-minute window.
        Returned when the authenticated API key has a per-minute rate limit.
      schema:
        type: integer
        minimum: 1
    RateLimitRemaining:
      description: >-
        Requests remaining in the current fixed one-minute window. Returned when
        the authenticated API key has a per-minute rate limit.
      schema:
        type: integer
        minimum: 0
    RateLimitReset:
      description: >-
        Unix timestamp in seconds when the current rate-limit window resets.
        Returned when the authenticated API key has a per-minute rate limit.
      schema:
        type: integer
  responses:
    RateLimited:
      description: Rate limit exceeded
      headers:
        X-RateLimit-Limit:
          $ref: '#/components/headers/RateLimitLimit'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/RateLimitRemaining'
        X-RateLimit-Reset:
          $ref: '#/components/headers/RateLimitReset'
        Retry-After:
          description: Seconds until the per-minute rate limit window resets
          schema:
            type: integer
            minimum: 1
            maximum: 60
      content:
        application/json:
          schema:
            type: object
            properties:
              message:
                type: string
                description: Error message
              error_code:
                type: string
                enum:
                  - RATE_LIMITED
                description: Error code indicating the rate limit was exceeded
              key_metadata:
                $ref: '#/components/schemas/KeyMetadata'
            required:
              - message
              - error_code
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        Bearer authentication header of the form `Bearer <API_KEY>`, where
        `<API_KEY>` is your api key.

````