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

# List monitors



## OpenAPI

````yaml https://api.hydrafetch.com/openapi.json get /v1/web/monitors
openapi: 3.0.0
info:
  title: Hydrafetch API
  description: >-
    Hydrafetch is a web data API for developers and AI agents. Give it a URL or
    a query and it returns clean markdown and structured data: scrape, crawl,
    map, search, news, jobs, extraction, brand data and screenshots, over one
    API and an MCP server. A page read costs one credit and a failed page costs
    nothing.


    Point us at a whole site and get every page. Ask a question and get answers
    with per-field

    confidence and the passage each value came from. You describe the outcome
    you want — the

    pipeline decides how to get it.


    ## Authentication


    Every request is authenticated with your API key in the `X-API-Key` header.
    Keys are scoped to a

    workspace and carry its credit balance.


    ## Credits


    Calls are billed in credits and charged only on success. A standard scrape
    is one credit; richer

    formats and the extraction tier cost more. Each response reports what it
    consumed.


    ## Conventions


    All timestamps are UTC ISO 8601. Long-running jobs (crawl, batch) return a
    job id you poll, or a

    webhook you register.


    ## Errors


    Every failure returns the same shape, whatever the status:


    ```json

    { "success": false, "error": { "code": "INSUFFICIENT_CREDITS", "message":
    "Insufficient credits" },
      "meta": { "requestId": "019e8a3c-9f0b-7c12-88ab-1d2e3f4a5b6c" } }
    ```


    Branch on `error.code`, which is stable. `error.message` is written for a
    person and may be

    reworded without notice. Validation failures add `error.details`. Quote
    `meta.requestId` when

    asking us about a specific failure. Every operation documents the codes it
    can return.


    ## Rate limits


    Limits are per workspace, not per key, over a 60 second window, and the
    ceiling comes from your

    plan. Every response carries the IETF RateLimit header fields so you can
    self-throttle rather

    than discovering the limit by hitting it:


    ```http

    RateLimit-Policy: "workspace";q=600;w=60

    RateLimit: "workspace";r=599;t=42

    ```


    `q` is the quota, `w` the window in seconds, `r` the requests remaining and
    `t` the seconds until

    the window resets. A 429 also carries `Retry-After` in seconds; wait that
    long rather than

    retrying immediately. The older `X-RateLimit-Limit`, `X-RateLimit-Remaining`
    and

    `X-RateLimit-Reset` headers are still sent and mean the same thing.


    ## Versioning and deprecation


    The version is in the path: every endpoint on this API lives under `/v1/`.
    Within a version we

    only make additive changes — new endpoints, new optional parameters, new
    fields in a response.

    Adding a field to a response is not a breaking change, so parse defensively
    and ignore what you

    do not recognise.


    Anything that would break an existing integration ships under a new version
    path instead. When an

    endpoint or a version is retired, the responses say so before it stops
    working:


    ```http

    Deprecation: @1780272000

    Sunset: Sat, 01 May 2027 00:00:00 GMT

    Link: <https://docs.hydrafetch.com/changelog>; rel="deprecation"

    ```


    `Deprecation` (RFC 9745) marks when the endpoint became deprecated, `Sunset`
    (RFC 8594) when it

    stops responding, and the `deprecation` link relation points at what to move
    to. Nothing on this

    API is deprecated today, so you will not see these headers yet. Watch for
    them rather than for an

    announcement: the headers are the notice, and the linked changelog carries
    what to move to.
  version: '1.0'
  contact:
    name: Hydrafetch
    url: https://hydrafetch.com
    email: support@hydrafetch.com
servers:
  - url: https://api.hydrafetch.com
    description: Production
security:
  - apiKey: []
tags:
  - name: Scrape
    description: >-
      Turn one URL into clean, LLM-ready content. Ask for Markdown, HTML, links,
      or the page’s own structured data, and poll a job id when a fetch runs
      long.
  - name: Crawl & batch
    description: >-
      Whole sites rather than single pages. Map every URL, crawl with depth and
      path rules, batch a list you already have, and read the webhook deliveries
      for either.
  - name: Search
    description: >-
      Search the web and get the ranked results back already scraped, so an
      agent has content to cite rather than links to fetch.
  - name: Extract
    description: >-
      Pull schema-shaped JSON out of one or many pages, with optional per-field
      confidence and the source passage behind each value.
  - name: Brand
    description: >-
      Resolve a domain into the company ready to render: logos for light and
      dark, the palette ranked by how the site uses it, fonts, socials, and the
      design system behind them.
  - name: Media
    description: >-
      Images and screenshots from a page, with source and alt text, or a
      rendered capture of the page as it appears.
paths:
  /v1/web/monitors:
    get:
      tags:
        - Monitors
      summary: List monitors
      operationId: monitorsList
      parameters:
        - name: limit
          required: false
          in: query
          schema:
            type: number
        - name: offset
          required: false
          in: query
          schema:
            type: number
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MonitorListDto'
        '400':
          description: The request body or query failed validation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebError'
              example:
                success: false
                error:
                  code: VALIDATION_ERROR
                  message: url must be a valid URL
                meta:
                  requestId: 019e8a3c-9f0b-7c12-88ab-1d2e3f4a5b6c
        '401':
          description: >-
            The X-API-Key header is missing, malformed, or names a key that no
            longer exists.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebError'
              example:
                success: false
                error:
                  code: UNAUTHORIZED
                  message: >-
                    Missing X-API-Key header. Agents:
                    https://hydrafetch.com/auth.md
                meta:
                  requestId: 019e8a3c-9f0b-7c12-88ab-1d2e3f4a5b6c
        '402':
          description: >-
            The workspace has no credits left for this request. Nothing was
            charged and nothing was fetched.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebError'
              example:
                success: false
                error:
                  code: INSUFFICIENT_CREDITS
                  message: Insufficient credits
                meta:
                  requestId: 019e8a3c-9f0b-7c12-88ab-1d2e3f4a5b6c
        '403':
          description: The key is valid but the workspace may not make this request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebError'
              example:
                success: false
                error:
                  code: WORKSPACE_BANNED
                  message: >-
                    This workspace has been suspended and cannot make API
                    requests.
                meta:
                  requestId: 019e8a3c-9f0b-7c12-88ab-1d2e3f4a5b6c
        '404':
          description: No such job, or the id belongs to another workspace.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebError'
              example:
                success: false
                error:
                  code: NOT_FOUND
                  message: Job not found
                meta:
                  requestId: 019e8a3c-9f0b-7c12-88ab-1d2e3f4a5b6c
        '422':
          description: >-
            The target site did not respond, or we could not read that page.
            This is a fact about that URL rather than a fault on our side, and
            retrying it will not change the answer. When
            details.retryAfterSeconds is present, asking again before then
            returns this same answer. Nothing was charged.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebError'
              example:
                success: false
                error:
                  code: UPSTREAM_UNREACHABLE
                  message: The origin did not respond to any attempt we made.
                meta:
                  requestId: 019e8a3c-9f0b-7c12-88ab-1d2e3f4a5b6c
        '429':
          description: >-
            The workspace exceeded its per-minute request limit. Read the
            RateLimit headers, or Retry-After on this response, and retry after
            the window resets.
          headers:
            Retry-After:
              description: >-
                Seconds to wait before retrying. Prefer this over a fixed
                backoff.
              schema:
                type: integer
                example: 17
            RateLimit:
              description: Requests remaining (r) and seconds until the window resets (t).
              schema:
                type: string
                example: '"workspace";r=0;t=17'
            RateLimit-Policy:
              description: >-
                The quota (q) for your plan and the window it applies over (w),
                in seconds.
              schema:
                type: string
                example: '"workspace";q=600;w=60'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebError'
              example:
                success: false
                error:
                  code: TOO_MANY_REQUESTS
                  message: Rate limit exceeded for this workspace and plan.
                meta:
                  requestId: 019e8a3c-9f0b-7c12-88ab-1d2e3f4a5b6c
        '500':
          description: Unexpected server error. Nothing was charged.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebError'
              example:
                success: false
                error:
                  code: INTERNAL_SERVER_ERROR
                  message: Internal server error
                meta:
                  requestId: 019e8a3c-9f0b-7c12-88ab-1d2e3f4a5b6c
        '503':
          description: >-
            A dependency needed for the requested formats is unavailable. Safe
            to retry.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebError'
              example:
                success: false
                error:
                  code: SERVICE_UNAVAILABLE
                  message: The summary and json formats are not available.
                meta:
                  requestId: 019e8a3c-9f0b-7c12-88ab-1d2e3f4a5b6c
components:
  schemas:
    MonitorListDto:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/MonitorResponseDto'
      required:
        - data
    WebError:
      type: object
      required:
        - success
        - error
        - meta
      description: >-
        Every failure on this API returns this shape, whatever the status.
        Successful responses never carry it.
      properties:
        success:
          type: boolean
          enum:
            - false
          example: false
        error:
          $ref: '#/components/schemas/WebErrorBody'
        meta:
          $ref: '#/components/schemas/WebErrorMeta'
    MonitorResponseDto:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        status:
          type: string
          enum:
            - active
            - paused
        pausedReason:
          type: string
          enum:
            - user
            - plan
            - failing
          nullable: true
        schedule:
          $ref: '#/components/schemas/MonitorScheduleResponseDto'
        targets:
          type: array
          items:
            oneOf:
              - $ref: '#/components/schemas/MonitorPagesTargetResponseDto'
              - $ref: '#/components/schemas/MonitorSiteTargetResponseDto'
              - $ref: '#/components/schemas/MonitorSearchTargetResponseDto'
            discriminator:
              propertyName: type
              mapping:
                pages: '#/components/schemas/MonitorPagesTargetResponseDto'
                site: '#/components/schemas/MonitorSiteTargetResponseDto'
                search: '#/components/schemas/MonitorSearchTargetResponseDto'
        webhook:
          nullable: true
          type: object
          allOf:
            - $ref: '#/components/schemas/MonitorWebhookResponseDto'
        retentionDays:
          type: number
        email:
          type: string
          enum:
            - 'off'
            - daily
        nextRunAt:
          type: string
          nullable: true
        lastRunAt:
          type: string
          nullable: true
        lastCheck:
          nullable: true
          type: object
          allOf:
            - $ref: '#/components/schemas/MonitorCheckSummaryDto'
        createdAt:
          type: string
      required:
        - id
        - name
        - status
        - pausedReason
        - schedule
        - targets
        - webhook
        - retentionDays
        - email
        - nextRunAt
        - lastRunAt
        - lastCheck
        - createdAt
    WebErrorBody:
      type: object
      required:
        - code
        - message
      properties:
        code:
          type: string
          enum:
            - VALIDATION_ERROR
            - INVALID_INPUT
            - UNAUTHORIZED
            - INSUFFICIENT_CREDITS
            - FORBIDDEN
            - WORKSPACE_BANNED
            - NOT_FOUND
            - IDEMPOTENCY_IN_PROGRESS
            - IDEMPOTENCY_KEY_REUSED
            - TOO_MANY_REQUESTS
            - UPSTREAM_UNREACHABLE
            - SERVICE_UNAVAILABLE
            - INTERNAL_SERVER_ERROR
          description: >-
            Stable, machine-readable reason. Branch on this rather than on the
            message, which may be reworded.
          example: INSUFFICIENT_CREDITS
        message:
          type: string
          description: Human-readable explanation. Safe to show a user, not to parse.
          example: Insufficient credits
        details:
          type: object
          additionalProperties: true
          description: Optional machine-readable context, present on validation failures.
    WebErrorMeta:
      type: object
      properties:
        requestId:
          type: string
          description: Quote this when contacting support about a specific failure.
          example: 019e8a3c-9f0b-7c12-88ab-1d2e3f4a5b6c
    MonitorScheduleResponseDto:
      type: object
      properties:
        every:
          type: string
          enum:
            - 15m
            - 30m
            - 1h
            - 2h
            - 6h
            - 12h
            - 1d
            - 7d
      required:
        - every
    MonitorPagesTargetResponseDto:
      type: object
      properties:
        type:
          type: string
          enum:
            - pages
          description: Watch a list of pages for changes to their content.
        urls:
          example:
            - https://example.com/pricing
          description: The pages to watch, up to 50.
          type: array
          items:
            type: string
        selector:
          example:
            - '#pricing'
            - .plan-card
          description: >-
            CSS selectors. Only the content inside them is compared, the rest of
            the page is ignored.
          type: array
          items:
            type: string
        ignore:
          example:
            - Last updated
            - '/^Visitors: \d+$/'
          description: >-
            Lines to leave out before comparing. Plain text matches anywhere in
            a line, ignoring case; wrap a pattern in slashes for a regular
            expression.
          type: array
          items:
            type: string
        triggerOn:
          example:
            - price
            - /sold out/i
          description: >-
            Only alert when an added or removed line contains one of these.
            Plain text or a regular expression in slashes. Every change is still
            kept in the history.
          type: array
          items:
            type: string
        scrapeOptions:
          description: >-
            How each page is read. The same options as a scrape; formats are
            chosen by the monitor.
          allOf:
            - $ref: '#/components/schemas/ScrapeOptionsDto'
        goal:
          type: string
          maxLength: 300
          example: the Pro plan price drops below $50 a month
          description: >-
            What you are watching for, in plain words. Each change is checked
            against it and only alerts when it matches; every change is still
            kept in the history with the verdict. One extra credit per change
            checked.
        id:
          type: string
          description: Stable id of this target within the monitor.
      required:
        - type
        - urls
        - id
    MonitorSiteTargetResponseDto:
      type: object
      properties:
        type:
          type: string
          enum:
            - site
          description: >-
            Watch a whole site for pages that appear or disappear. Each new page
            is read once for its title and opening lines.
        url:
          type: string
          example: https://example.com/blog
          description: Where the site starts.
        includePaths:
          example:
            - ^/blog/.*
          description: Only count pages whose path matches one of these patterns.
          type: array
          items:
            type: string
        excludePaths:
          example:
            - ^/blog/tag/.*
          description: Leave out pages whose path matches one of these patterns.
          type: array
          items:
            type: string
        limit:
          type: number
          minimum: 1
          maximum: 1000
          default: 200
          description: >-
            The most pages to track. When a site has more, new pages are still
            found but none are reported as removed.
        readNewPages:
          type: boolean
          default: true
          description: >-
            Read each new page once for its title and opening lines, up to 20 a
            check, at one credit each. Off reports the address only.
        goal:
          type: string
          maxLength: 300
          example: new senior backend roles
          description: >-
            What you are watching for, in plain words. Each change is checked
            against it and only alerts when it matches; every change is still
            kept in the history with the verdict. One extra credit per change
            checked.
        id:
          type: string
          description: Stable id of this target within the monitor.
      required:
        - type
        - url
        - id
    MonitorSearchTargetResponseDto:
      type: object
      properties:
        query:
          type: string
          maxLength: 500
          example: best open source vector databases
          description: What to search the web for.
        timeRange:
          type: string
          enum:
            - day
            - week
            - month
            - year
          example: week
          description: Restrict results to a recency window relative to now.
        country:
          type: string
          example: us
          description: ISO 3166 alpha-2 country code to bias results toward a region.
        includeDomains:
          maxItems: 15
          example:
            - github.com
            - arxiv.org
          description: Only return results from these domains.
          type: array
          items:
            type: string
        excludeDomains:
          maxItems: 15
          example:
            - pinterest.com
          description: Drop results from these domains.
          type: array
          items:
            type: string
        type:
          type: string
          enum:
            - search
          description: >-
            Run a search on a schedule and report results it has never returned
            before. Checks at most once an hour.
        limit:
          type: number
          minimum: 1
          maximum: 20
          default: 10
          description: How many top results to look at each time.
        goal:
          type: string
          maxLength: 300
          example: news about the company being acquired
          description: >-
            What you are watching for, in plain words. Each change is checked
            against it and only alerts when it matches; every change is still
            kept in the history with the verdict. One extra credit per change
            checked.
        id:
          type: string
          description: Stable id of this target within the monitor.
      required:
        - query
        - type
        - id
    MonitorWebhookResponseDto:
      type: object
      properties:
        url:
          type: string
        events:
          type: array
          items:
            type: string
            enum:
              - change
              - completed
      required:
        - url
        - events
    MonitorCheckSummaryDto:
      type: object
      properties:
        id:
          type: string
        status:
          type: string
          enum:
            - running
            - completed
            - partial
            - failed
            - skipped_no_credits
            - skipped_overlap
        trigger:
          type: string
          enum:
            - scheduled
            - manual
        totalPages:
          type: number
          description: Pages this check reads.
        same:
          type: number
        changed:
          type: number
        new:
          type: number
        removed:
          type: number
        error:
          type: number
          description: Pages we could not read this time. Never counted as a change.
        creditsUsed:
          type: number
        startedAt:
          type: string
        finishedAt:
          type: string
          nullable: true
      required:
        - id
        - status
        - trigger
        - totalPages
        - same
        - changed
        - new
        - removed
        - error
        - creditsUsed
        - startedAt
        - finishedAt
    ScrapeOptionsDto:
      type: object
      properties:
        formats:
          type: array
          example:
            - markdown
          description: What to return per page. Omit for Markdown only.
          items:
            type: string
            enum:
              - markdown
              - html
              - rawHtml
              - links
              - structured
        onlyMainContent:
          type: boolean
          description: Return only the main content, dropping boilerplate. Default true.
        includeTags:
          maxItems: 50
          description: CSS selectors to keep.
          type: array
          items:
            type: string
        excludeTags:
          maxItems: 50
          description: CSS selectors to strip before extraction.
          type: array
          items:
            type: string
        removeBase64Images:
          type: boolean
          description: Strip inline base64 images. Default true.
        blockAds:
          type: boolean
          description: Remove ads and tracking elements. Default true.
        dismissCookies:
          type: boolean
          description: >-
            Remove cookie and consent banners. Default true. Set false to keep
            them; a banner the site adds with scripts after load is kept only
            when the page is rendered.
        dismissPopups:
          type: boolean
          description: >-
            Close newsletter and promotion popups when the page is rendered.
            Default true. Set false to keep them.
        render:
          type: boolean
          description: >-
            Always read the page in a browser, as a visitor sees it once its
            scripts have run. Default false: the page is read in a browser only
            when its HTML is not enough. Combine with dismissCookies and
            dismissPopups set to false to keep what scripts add after load.
        includeLinks:
          type: boolean
          description: >-
            Keep inline links in the markdown. By default links are kept
            wherever the page text carries them. Set true to keep them on every
            page, or false for the densest prose.
        waitFor:
          type: integer
          minimum: 0
          maximum: 30000
          description: Extra milliseconds to let the page settle before capture.
        waitForSelector:
          type: string
          maxLength: 500
          example: .price
          description: >-
            A CSS selector to wait for before capture. The page is rendered in a
            browser and read once an element matching it exists, or when the
            time budget runs out, in which case the result says the element
            never appeared.
        mobile:
          type: boolean
          description: >-
            Render the page as a phone would see it: a phone-sized screen, touch
            and a mobile browser identity. Use it for sites that serve different
            content to phones.
        timeout:
          type: integer
          minimum: 1000
          maximum: 100000
          description: Per-page time budget, in milliseconds.
        location:
          $ref: '#/components/schemas/LocationDto'
        headers:
          type: object
          additionalProperties:
            type: string
          description: Extra request headers to send when fetching each page.
        preferStructure:
          type: boolean
          description: Preserve document structure over prose density. Default off.
        maxAge:
          type: integer
          minimum: 0
          maximum: 604800000
          description: Serve a page from cache if younger than this many milliseconds.
    LocationDto:
      type: object
      properties:
        country:
          type: string
          example: us
          description: >-
            Two-letter country to read the page from: `us` or `de`. Any other
            country is refused with a 400 that lists the supported codes.
        languages:
          example:
            - en-US
            - en
          description: Preferred content languages, most-preferred first.
          type: array
          items:
            type: string
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: X-API-Key

````

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