Audit starten · REST API

Start a full audit The same as the Run audit button: one crawl per website at a time, and at most 3 audits per website in 24 hours through the API and MCP. Answers at once; poll GET /sites/{siteId}/audits/{auditId}.

Die Beschreibungen kommen aus dem OpenAPI-Dokument und sind auf Englisch.

Parameter

Name	Ort	Details
`siteId`Pflicht	Pfad	stringWebsite id, from GET /sites.

Anfrage (Body)

Feld	Details
`pageBudget`	integer · min 1; Most pages to crawl: at least 50 (or the plan limit when lower), at most the plan's pages per audit. Default: the website's audit budget, capped at that limit. A bigger budget than the website's own gets a longer time limit (at most 120 minutes).

{
  "pageBudget": 500
}

Antwort

202 · application/json

Feld	Details
`queued`	true or false · required; Always true
`auditId`	string · required; Id to poll
`status`	queued \| running \| done \| failed \| cancelled · required; queued
`pageBudget`	integer · required; Most pages it crawls
`timeLimitMinutes`	integer · required; Time limit, in minutes
`cappedByPlan`	true or false · required; True when the plan's limit lowered the budget
`planLimit`	integer · required; The plan's pages per audit
`startsLeftToday`	integer · required; API and MCP starts left in the 24 hours
`poll`	string · required; Where to poll its status
`link`	string · required; The Audit screen in the app
`note`	string · required; What happens next

Hinweise

Der Aufruf antwortet sofort mit 202, einer auditId und einer poll-Adresse; verfolgen Sie das Audit mit GET /sites/{siteId}/audits/{auditId} etwa einmal pro Minute. pageBudget ist optional und darf höchstens die Seiten pro Audit Ihres Tarifs betragen: Free 200, Starter 500, Agency 1.000, Enterprise 10.000. Pro Website läuft immer nur ein Crawl, und über API und MCP lassen sich höchstens 3 Audits pro Website und Tag starten. Das wöchentliche Audit läuft wie gewohnt.

Fehler

Status	Bedeutung
`400`	Bad request. Codes: `bad_page_budget`, `over_plan_limit`.
`401`	Missing, unknown or revoked key. Codes: `missing_key`, `invalid_key`.
`403`	The key lacks the scope, covers another website, or its owner lost access. Codes: `missing_scope`, `other_site`, `owner_left`, `no_owner`, forbidden.
`404`	Not found. Codes: `not_found`.
`409`	Conflict with the current state. Codes: `already_running`.
`429`	A limit is reached. `rate_limited`: too many requests this hour for this key. Codes: `rate_limited`, `too_many_audits`.

Beispielanfrage

curl -X POST \
  -H "Authorization: Bearer mr_ws_…" \
  -H "Content-Type: application/json" \
  -d '{"pageBudget":500}' \
  "https://app.monoranks.com/api/v1/sites/SITE_ID/audits"

const res = await fetch("https://app.monoranks.com/api/v1/sites/SITE_ID/audits", {
  method: "POST",
  headers: { Authorization: "Bearer mr_ws_…", "Content-Type": "application/json" },
  body: JSON.stringify({
    "pageBudget": 500
  }),
});
if (!res.ok) throw new Error((await res.json()).error.message);
const data = await res.json();

import requests

res = requests.post(
    "https://app.monoranks.com/api/v1/sites/SITE_ID/audits",
    headers={"Authorization": "Bearer mr_ws_…"},
    json={
        "pageBudget": 500,
    },
)
res.raise_for_status()
data = res.json()

<?php
$ch = curl_init("https://app.monoranks.com/api/v1/sites/SITE_ID/audits");
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => "POST",
    CURLOPT_HTTPHEADER => ["Authorization: Bearer mr_ws_…", "Content-Type: application/json"],
    CURLOPT_POSTFIELDS => '{"pageBudget":500}',
    CURLOPT_RETURNTRANSFER => true,
]);
$data = json_decode(curl_exec($ch), true);

import axios from "axios";

const { data } = await axios.post(
  "https://app.monoranks.com/api/v1/sites/SITE_ID/audits",
  {
    "pageBudget": 500
  },
  { headers: { Authorization: "Bearer mr_ws_…" } },
);

Beispielantwort

{
  "queued": true,
  "auditId": "d4f6a8c0-2e4a-4c6e-8a0c-4e6a8c0e2a4b",
  "status": "queued",
  "pageBudget": 500,
  "timeLimitMinutes": 30,
  "cappedByPlan": false,
  "planLimit": 500,
  "startsLeftToday": 2,
  "poll": "https://app.monoranks.com/api/v1/sites/3f6c2a1e-8b4d-4c7a-9e21-5d0b7a6f4c13/audits/d4f6a8c0-2e4a-4c6e-8a0c-4e6a8c0e2a4b",
  "link": "https://app.monoranks.com/sites/3f6c2a1e-8b4d-4c7a-9e21-5d0b7a6f4c13/audit",
  "note": "Queued: a full audit crawls the website, then rebuilds issues, scores and the llms.txt draft."
}

{
  "error": {
    "code": "bad_page_budget",
    "message": "pageBudget must be at least 50."
  }
}

{
  "error": {
    "code": "missing_key",
    "message": "Send the key as Authorization: Bearer mr_site_…"
  }
}

{
  "error": {
    "code": "missing_scope",
    "message": "This key does not have the scope this call needs."
  }
}

{
  "error": {
    "code": "not_found",
    "message": "Website not found."
  }
}

{
  "error": {
    "code": "already_running",
    "message": "An audit of this website is already running (id d4f6a8c0-2e4a-4c6e-8a0c-4e6a8c0e2a4b); one crawl runs at a time.",
    "auditId": "d4f6a8c0-2e4a-4c6e-8a0c-4e6a8c0e2a4b",
    "kind": "audit",
    "status": "running",
    "poll": "https://app.monoranks.com/api/v1/sites/3f6c2a1e-8b4d-4c7a-9e21-5d0b7a6f4c13/audits/d4f6a8c0-2e4a-4c6e-8a0c-4e6a8c0e2a4b"
  }
}

{
  "error": {
    "code": "rate_limited",
    "message": "More than 1200 requests this hour for this key."
  }
}

Der MCP-Server macht dasselbe mit dem Tool start_audit.