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

# POST /monitor/{id}/run

> Run a monitor's check now instead of waiting for its schedule. Billed like a scheduled check.

## Overview

Queues a check outside the schedule and returns it straight away, with status `queued`. The check runs within seconds; poll [`GET /monitor/{id}/checks/{checkId}`](/api-reference/endpoint/monitor-check) until its status is no longer `queued` or `running`.

Use it to take the first baseline right after creating a monitor, to check a page on demand, or to try a new goal. It works on paused monitors too, and does not move the schedule.

## Example request

<CodeGroup>
  ```bash cURL theme={"theme":"css-variables"}
  curl -X POST "https://api.prefetch.io/monitor/mon_3f9a1c2b7d4e4f6a8b0c1d2e3f4a5b6c/run" \
    -H "X-API-Key: $PREFETCH_API_KEY"
  ```

  ```javascript Node.js theme={"theme":"css-variables"}
  const base = "https://api.prefetch.io";
  const headers = { "X-API-Key": process.env.PREFETCH_API_KEY };

  const run = await fetch(`${base}/monitor/${monitorId}/run`, { method: "POST", headers });
  const { data: queued } = await run.json();

  // Wait for the check, then show only what changed.
  let check;
  do {
    await new Promise((r) => setTimeout(r, 3000));
    const res = await fetch(`${base}/monitor/${monitorId}/checks/${queued.id}?status=changed`, { headers });
    ({ data: check } = await res.json());
  } while (check.status === "queued" || check.status === "running");

  for (const page of check.pages) console.log(page.url, page.diff?.text ?? page.diff?.fields);
  ```

  ```python Python theme={"theme":"css-variables"}
  import os, time, requests

  base = "https://api.prefetch.io"
  headers = {"X-API-Key": os.environ["PREFETCH_API_KEY"]}

  queued = requests.post(f"{base}/monitor/{monitor_id}/run", headers=headers).json()["data"]

  while True:
      time.sleep(3)
      check = requests.get(
          f"{base}/monitor/{monitor_id}/checks/{queued['id']}",
          params={"status": "changed"},
          headers=headers,
      ).json()["data"]
      if check["status"] not in ("queued", "running"):
          break

  for page in check["pages"]:
      print(page["url"], page["diff"])
  ```
</CodeGroup>

## Example response

```json theme={"theme":"css-variables"}
{
  "success": true,
  "data": {
    "id": "chk_8e2d4f6a1b3c4d5e6f7a8b9c0d1e2f3a",
    "monitor_id": "mon_3f9a1c2b7d4e4f6a8b0c1d2e3f4a5b6c",
    "status": "queued",
    "trigger": "manual",
    "scheduled_for": null,
    "started_at": null,
    "finished_at": null,
    "estimated_credits": 55,
    "actual_credits": 0,
    "summary": { "total_pages": 0, "same": 0, "new": 0, "changed": 0, "removed": 0, "error": 0 },
    "target_results": null,
    "error": null,
    "created_at": "2026-10-09T10:05:00.000Z",
    "updated_at": "2026-10-09T10:05:00.000Z"
  },
  "meta": {
    "requestId": "a3e6c7d8-9f0a-4b12-93c4-5e6f708192a3",
    "durationMs": 38
  }
}
```

The status is `202 Accepted` — the check has been queued, not run.

## One check at a time

A monitor runs one check at a time. If one is already queued or running, this returns `409` and names it — wait for it to finish rather than retrying in a loop. The same rule applies to scheduled checks: one that comes due while the previous is still running is recorded as `skipped_overlap` instead of running alongside it.

## Credits

A manual check is billed exactly like a scheduled one: 1 credit per page fetched (4 on targets tracking `json`), plus 1 per changed page judged against the goal. `estimated_credits` is the upper bound; `actual_credits` on the finished check is what was charged.

## Related

<CardGroup cols={2}>
  <Card title="GET /monitor/{id}/checks/{checkId}" icon="code-compare" href="/api-reference/endpoint/monitor-check">
    Read the check's results.
  </Card>

  <Card title="POST /monitor" icon="eye" href="/api-reference/endpoint/monitor">
    How monitors detect and report changes.
  </Card>
</CardGroup>


## OpenAPI

````yaml POST /monitor/{id}/run
openapi: 3.1.0
info:
  title: Prefetch API
  description: >-
    Extract brand identity, company data, screenshots, IAB classifications, and
    clean page content from any URL.
  version: 1.0.0
  contact:
    email: support@prefetch.io
servers:
  - url: https://api.prefetch.io
    description: Production
security:
  - apiKey: []
tags:
  - name: Endpoints
    description: Data extraction endpoints. All require authentication and consume credits.
  - name: Health
    description: Health and readiness probes. No authentication required.
paths:
  /monitor/{id}/run:
    post:
      tags:
        - Endpoints
      summary: Run a check now
      description: >-
        Queues a check outside the schedule and returns it immediately. Poll
        `GET /monitor/{id}/checks/{checkId}` for the result. Works on paused
        monitors too.


        **Credit cost: the same as a scheduled check** — 1 per page fetched (4
        in `json` mode), plus 1 per changed page judged.
      operationId: runMonitor
      parameters:
        - $ref: '#/components/parameters/monitorId'
      responses:
        '202':
          description: Check queued.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    enum:
                      - true
                  data:
                    $ref: '#/components/schemas/MonitorCheckData'
                  meta:
                    $ref: '#/components/schemas/Meta'
                required:
                  - success
                  - data
                  - meta
              example:
                success: true
                data:
                  id: chk_8e2d4f6a1b3c4d5e6f7a8b9c0d1e2f3a
                  monitor_id: mon_3f9a1c2b7d4e4f6a8b0c1d2e3f4a5b6c
                  status: queued
                  trigger: manual
                  scheduled_for: null
                  started_at: null
                  finished_at: null
                  estimated_credits: 55
                  actual_credits: 0
                  summary:
                    total_pages: 0
                    same: 0
                    new: 0
                    changed: 0
                    removed: 0
                    error: 0
                  target_results: null
                  error: null
                  created_at: '2026-10-09T10:05:00.000Z'
                  updated_at: '2026-10-09T10:05:00.000Z'
                meta:
                  requestId: a3e6c7d8-9f0a-4b12-93c4-5e6f708192a3
                  durationMs: 38
        '400':
          description: Invalid or missing parameters. The message names the field.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Missing API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: >-
            Revoked key, expired key, credit limit, blocklisted URL, monitor
            limit reached, or a RapidAPI subscription — monitors need a direct
            Prefetch API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: >-
            Monitor not found — or not yours. Monitor ids are unguessable, so
            another key's monitor is reported as not found rather than
            forbidden.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: >-
            A check is already queued or running for this monitor. The message
            names it.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Rate limit exceeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Monitoring is temporarily unavailable. Retry shortly.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  parameters:
    monitorId:
      name: id
      in: path
      required: true
      description: The monitor id returned by `POST /monitor`.
      schema:
        type: string
        example: mon_3f9a1c2b7d4e4f6a8b0c1d2e3f4a5b6c
  schemas:
    MonitorCheckData:
      type: object
      properties:
        id:
          type: string
          example: chk_8e2d4f6a1b3c4d5e6f7a8b9c0d1e2f3a
        monitor_id:
          type: string
        status:
          type: string
          enum:
            - queued
            - running
            - completed
            - failed
            - partial
            - skipped_overlap
            - skipped_no_credits
          description: >-
            `partial`: some pages errored, or the check stopped early on credits
            or its time limit — its results are real but incomplete.
            `skipped_overlap`: the previous check was still running.
            `skipped_no_credits`: the owning key had no credits or was revoked.
            Skipped checks are never charged.
        trigger:
          type: string
          enum:
            - scheduled
            - manual
        scheduled_for:
          type: string
          format: date-time
          nullable: true
        started_at:
          type: string
          format: date-time
          nullable: true
        finished_at:
          type: string
          format: date-time
          nullable: true
        estimated_credits:
          type: integer
          nullable: true
          description: Upper bound, computed when the check was queued.
        actual_credits:
          type: integer
          description: >-
            What the check was charged: pages fetched at the `/scrape` rate,
            plus pages judged.
        summary:
          $ref: '#/components/schemas/MonitorSummary'
        target_results:
          type: array
          nullable: true
          items:
            type: object
          description: >-
            Per target: pages checked, and for crawls whether the crawl ran to
            completion. Only a complete crawl can report removed pages.
        error:
          type: string
          nullable: true
          description: >-
            Why the check is partial, failed or skipped, or what it could not
            do.
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
    Meta:
      type: object
      properties:
        requestId:
          type: string
          format: uuid
          description: Unique identifier for this request.
          example: a3f2c1d4-7b6e-4f2a-9c1d-8e3f2a1b4c5d
        durationMs:
          type: integer
          nullable: true
          description: Time taken to process the request in milliseconds.
          example: 1842
      required:
        - requestId
        - durationMs
    ErrorResponse:
      type: object
      properties:
        success:
          type: boolean
          enum:
            - false
          description: >-
            Always false. Absent, like `meta`, on authentication and rate-limit
            errors, which are answered before a request is processed.
        error:
          type: string
          description: >-
            Human-readable error message. The wording can change: branch on
            `error_code`.
          example: Credit limit exceeded
        error_code:
          type: string
          enum:
            - INVALID_REQUEST
            - PAYLOAD_TOO_LARGE
            - NOT_FOUND
            - CONFLICT
            - UNAUTHORIZED
            - FORBIDDEN
            - CREDITS_EXHAUSTED
            - RATE_LIMITED
            - CONCURRENCY_LIMITED
            - URL_BLOCKED
            - URL_NOT_PERMITTED
            - DNS_RESOLUTION_FAILED
            - TARGET_BLOCKED
            - TARGET_CONNECTION_FAILED
            - TARGET_TIMEOUT
            - TARGET_SSL_ERROR
            - TARGET_SERVER_ERROR
            - TARGET_CLIENT_ERROR
            - TARGET_NOT_A_PAGE
            - TARGET_UNLOADABLE
            - RESEARCH_INCONCLUSIVE
            - TIMEOUT
            - SERVICE_BUSY
            - SERVICE_UNAVAILABLE
            - INTERNAL_ERROR
          description: >-
            What went wrong, for machines. Stable: a code keeps its meaning once
            published. See [Error handling](/concepts/errors).
          example: CREDITS_EXHAUSTED
        retryable:
          type: boolean
          description: >-
            Whether the same request can succeed if sent again after a short
            wait (honour `Retry-After` when present). False for problems with
            the request or the target.
          example: false
        retryAfterSeconds:
          type: integer
          description: 'On `RATE_LIMITED`: seconds until a request will be accepted.'
        limit:
          type: integer
          description: >-
            On `CONCURRENCY_LIMITED`: how many requests this key may have in
            flight.
        meta:
          $ref: '#/components/schemas/Meta'
      required:
        - error
        - error_code
        - retryable
    MonitorSummary:
      type: object
      properties:
        total_pages:
          type: integer
        same:
          type: integer
        new:
          type: integer
        changed:
          type: integer
        removed:
          type: integer
        error:
          type: integer
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: X-API-Key
      description: Your Prefetch API key. Obtain one from the dashboard.

````

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