Runs

List the site audits

seo_site_auditor.runs.list

Lists the organization's site audits, newest first, paginated by cursor (limit up to 200); site_id narrows it to one site. Each audit has its status (pending: queued; crawling; analyzing; completed; completed_with_errors: finished but some pages could not be read; failed: error says why), how it started (triggered_by manual or schedule), its timestamps and, once finished, health_score (0–100) with the share of pages it could read (coverage, low_coverage), geo_readiness_score, total_pages, total_issues, issues_by_severity, crawl_stats and crawl_method. status filters on the page read, so a page can bring fewer than limit while has_more is true: follow next_cursor. A site keeps its last 52 audits. Requires view access to Site Audit.

Scope

seo_site_auditor:read

Permission

View the module

MCP tool

seo_site_auditor_runs_listOn the full surface; on the compact one, mb_execute_operation with id: "seo_site_auditor.runs.list".

Declared cost: up to 201 reads and 0 writes per call (they count against the daily quota).

Parameters

Response

Errors

Example

curl "https://api.mb-suite.com/v1/seo/site-auditor/runs" \
  -H "Authorization: Bearer $MB_API_KEY"

Try it with your test API key

With a test API key the request always goes to your practice organization: example data you can reset.

curl "https://api.mb-suite.com/v1/seo/site-auditor/runs" \
  -H "Authorization: Bearer $MB_TEST_KEY"

Get one site audit with its scores

seo_site_auditor.runs.get

Returns one site audit: status, timestamps, health_score with the score of each category (category_scores: crawling, meta_tags, content, links, images, speed, security, sitemaps, redirects, usability, resources, localization, structured_data, open_graph), issues_by_severity, the PageSpeed Insights results of the sampled pages (psi_results: Lighthouse scores and Core Web Vitals, rounded; include_psi_details: true adds the opportunities, diagnostics and agentic-browsing checks, tens of thousands of characters in a large audit), the GEO readiness checks (geo_checks: what AI search engines need), site-level checks the site blocked (site_level_blocks), crawl_stats with coverage and low_coverage (health_score is computed only over the pages that could be read: under 20% read, it says little about the site) and error. The issues are in seo_site_auditor.issues.list and the pages in seo_site_auditor.pages.list. Not found (audit_run_not_found) if the audit does not exist. Requires view access to Site Audit.

Scope

seo_site_auditor:read

Permission

View the module

MCP tool

seo_site_auditor_runs_getOn the full surface; on the compact one, mb_execute_operation with id: "seo_site_auditor.runs.get".

Declared cost: up to 2 reads and 0 writes per call (they count against the daily quota).

Parameters

Response

Errors

Example

curl "https://api.mb-suite.com/v1/seo/site-auditor/runs/{run_id}" \
  -H "Authorization: Bearer $MB_API_KEY"

Try it with your test API key

With a test API key the request always goes to your practice organization: example data you can reset.

curl "https://api.mb-suite.com/v1/seo/site-auditor/runs/{run_id}" \
  -H "Authorization: Bearer $MB_TEST_KEY"

Start an audit of a site now

seo_site_auditor.runs.trigger

Starts an audit of a site now: MB Suite's auditor crawls up to the site's max_pages pages, runs PageSpeed Insights on a sample and checks SEO, speed, security and GEO readiness (each issue in the language of the person who starts it). Returns the new run_id right away; the audit runs in the background, usually 5 to 30 minutes depending on the site. dispatched=false means the service did not answer in time: the audit stays queued and the service can still take it (if not, it is marked failed within 15 minutes). When it finishes, the site's notify_emails get the results by email. Fails without starting anything when another audit of the site is queued or running (audit_in_progress, 409, with its run_id), in demo organizations (demo_read_only, 403), from an API key or app after 5 audits of the site started that way in 24 hours (daily_limit_reached, 429, resource site_audits, with retry_after; scheduled audits are not affected), and while the audit service is not available (audit_service_unavailable, 503 with retry_after); when the service rejects it (audit_dispatch_failed, 500) the audit is left as failed. Not idempotent: each call that succeeds starts an audit. Requires edit access to Site Audit.

Needs confirmation: first dry_run: true (preview and confirm_token, valid 10 minutes and for one run), then the same body with confirm_token. In a few operations only with certain data: the description says when. Why and how: Dry run and confirm_token.

Scope

seo_site_auditor:write

Permission

Edit in the module

MCP tool

seo_site_auditor_runs_triggerOn the full surface; on the compact one, mb_execute_operation with id: "seo_site_auditor.runs.trigger".

Declared cost: up to 55 reads and 2 writes per call (they count against the daily quota). Touches an external platform (cloud_run): it counts against the external operations quota.

Parameters

Response

Errors

Example

curl -X POST "https://api.mb-suite.com/v1/seo/site-auditor/sites/{site_id}/runs" \
  -H "Authorization: Bearer $MB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "dry_run": true
}'

Try it with your test API key

With a test API key the request always goes to your practice organization: example data you can reset. In the practice organization this operation is not simulated (it reaches another platform): it answers 409 sandbox_external_unavailable.

Delete one site audit

seo_site_auditor.runs.delete

Deletes one finished audit for good, with its issues and its crawled pages. It does NOT go to the trash and cannot be undone; the site and its other audits are kept (if it was the site's latest, the site then shows the previous finished one). An audit still queued or running cannot be deleted (audit_in_progress, 409). Outside the screen it requires a dry run (which counts what will be deleted) and a confirm_token. Not found (audit_run_not_found) if the audit does not exist. Requires edit access to Site Audit and, for a credential, deletion enabled.

Needs confirmation: first dry_run: true (preview and confirm_token, valid 10 minutes and for one run), then the same body with confirm_token. In a few operations only with certain data: the description says when. Why and how: Dry run and confirm_token.

Scope

seo_site_auditor:write and “Allow deletions” (seo_site_auditor:delete in OAuth)

Permission

Edit in the module

MCP tool

seo_site_auditor_runs_deleteOn the full surface; on the compact one, mb_execute_operation with id: "seo_site_auditor.runs.delete".

Declared cost: up to 25 reads and 30 writes per call (they count against the daily quota).

Parameters

Response

Errors

Example

curl -X DELETE "https://api.mb-suite.com/v1/seo/site-auditor/runs/{run_id}" \
  -H "Authorization: Bearer $MB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "dry_run": true
}'

Try it with your test API key

With a test API key the request always goes to your practice organization: example data you can reset.

curl -X DELETE "https://api.mb-suite.com/v1/seo/site-auditor/runs/{run_id}" \
  -H "Authorization: Bearer $MB_TEST_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "dry_run": true
}'

Delete several site audits

seo_site_auditor.runs.bulk.delete

Deletes up to 200 finished audits for good, each with its issues and crawled pages (repeated ids count once). They do NOT go to the trash and it cannot be undone. Ids that do not exist come back in not_found and audits still queued or running are skipped and come back in in_progress: neither fails the batch. Outside the screen it always needs a dry run (the preview counts what will be deleted and lists what will be skipped) and its confirm_token. Returns deleted, deleted_run_ids, not_found and in_progress. Requires edit access to Site Audit and, for a credential, deletion enabled.

Needs confirmation: first dry_run: true (preview and confirm_token, valid 10 minutes and for one run), then the same body with confirm_token. In a few operations only with certain data: the description says when. Why and how: Dry run and confirm_token.

Scope

seo_site_auditor:write and “Allow deletions” (seo_site_auditor:delete in OAuth)

Permission

Edit in the module

MCP tool

seo_site_auditor_runs_bulk_deleteOn the full surface; on the compact one, mb_execute_operation with id: "seo_site_auditor.runs.bulk.delete".

Declared cost: up to 450 reads and 1000 writes per call (they count against the daily quota).

Parameters

Response

Errors

Example

curl -X POST "https://api.mb-suite.com/v1/seo/site-auditor/runs/bulk/delete" \
  -H "Authorization: Bearer $MB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "run_ids": [
    "RUN_ID"
  ],
  "dry_run": true
}'

Try it with your test API key

With a test API key the request always goes to your practice organization: example data you can reset.

curl -X POST "https://api.mb-suite.com/v1/seo/site-auditor/runs/bulk/delete" \
  -H "Authorization: Bearer $MB_TEST_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "run_ids": [
    "RUN_ID"
  ],
  "dry_run": true
}'

Export a site audit to PDF

seo_site_auditor.runs.export_pdf

Renders a finished audit to an A4 PDF and returns a signed download link that expires in 24 hours, plus the file name and size. variant=full (default) has every section with the page list; variant=commercial is the summary for a client meeting. lang picks the document language (es, en, pt-BR; default the caller's). Rendering can take tens of seconds: while the PDF service is not available it answers pdf_unavailable (503 with retry_after: retry then); an audit too heavy to render in time answers pdf_render_timeout (409: the same request will time out again, try variant=commercial, the summary without the page list). An audit that failed or is still running has nothing to export (audit_not_completed, 409). Not idempotent: each call renders a new file. It changes nothing in MB Suite, so a read-only credential can run it (it is a read with the cost of rendering). Requires view access to Site Audit; not available in the public demo (403 demo_read_only).

Scope

seo_site_auditor:read

Permission

View the module

MCP tool

seo_site_auditor_runs_export_pdfOn the full surface; on the compact one, mb_execute_operation with id: "seo_site_auditor.runs.export_pdf".

Declared cost: up to 2 reads and 0 writes per call (they count against the daily quota). Touches an external platform (pdf): it counts against the external operations quota.

Parameters

Response

Errors

Example

curl -X POST "https://api.mb-suite.com/v1/seo/site-auditor/runs/{run_id}/export-pdf" \
  -H "Authorization: Bearer $MB_API_KEY"

Try it with your test API key

With a test API key the request always goes to your practice organization: example data you can reset. In the practice organization this operation is not simulated (it reaches another platform): it answers 409 sandbox_external_unavailable.