---
title: "Connector reference - bseoa | Tools, limits and errors"
description: "How the bseoa connector works: every tool with its inputs and outputs, crawl limits, the page budget and retention on hosted, what each error code means and what to do about it."
image: "https://www.blackseoanalyzer.com/static/images/black-seo-analyzer-og-image.png"
canonical: "https://www.blackseoanalyzer.com/en/connector-reference"
language: "en"
---

# Connector reference

What each tool does, what it returns, where the limits are, and what every error means. This is the page your assistant reads when you ask it how bseoa works.

## Local and hosted

The connector is bseoa as your assistant experiences it: a set of tools it calls directly. There are two ways to run it, and the tools are the same in both.

- **Local**: `bseoa mcp` runs on your machine, started by Claude Desktop, Claude Code, Cursor, Codex or another desktop host. Crawls run from your machine, with your license, and results are written to the SQLite database at `--db-path`. JavaScript rendering, semantic analysis, external link checking and CrUX field data are all available. Set up is on the [connector page](https://www.blackseoanalyzer.com/en/mcp).
- **Hosted**: when you connect from a chat tool that cannot start a local process, the tools run on our servers for your signed-in account. Crawls are queued, one at a time per account, and results are kept per account so they persist between conversations. Hosted crawls do not render JavaScript, do not run semantic analysis, do not check external links and do not fetch CrUX data; the hosted crawler identifies itself as `BlackSEOAnalyzer-Hosted`, obeys robots.txt and sends at most two requests a second to a site ([how to block it](https://www.blackseoanalyzer.com/en/crawler)).

Results persist in both modes: a crawl you ran yesterday can be read today with `list_crawls` and the session id it returns.

## The tools

| Tool | Takes | Returns | Use it when |
| --- | --- | --- | --- |
| check_page | `url`, optional `spa` (local only) | The page's issues in seconds. Never follows links. | The question is about one page. On hosted it does not count against the page budget. |
| start_crawl | `url`, optional `max_pages` (default 500), `spa` (local only) | A `job_id` immediately; the crawl continues in the background. | A whole site. Poll `crawl_status` until it is finished before reading results. |
| crawl_status | `job_id` | `state` (queued, running, finished or failed), pages crawled so far, and the `session_id` once there is one. | Waiting on a crawl. A failed job carries its `error`. |
| list_crawls | nothing | Every stored crawl session: id, start URL, dates, page count. | Finding "yesterday's crawl". Other tools default to the newest session when none is named. |
| issues_summary | optional `session_id` | Counts by severity, category and issue key, with example URLs for each key. | Always before `query_issues`; it is small and shows which keys are worth drilling into. |
| query_issues | optional `session_id`, `min_severity`, `key`, `category`, `url_prefix`, `offset` | Individual issues, at most 100 per call, with `next_offset` when there are more. | The detail behind a summary line. Filter; do not page through a whole site. |
| page_report | `url`, optional `session_id` | Everything recorded about one crawled URL: status, redirect, title, description, headings, counts, timings and its issues. Never the page HTML. | The context behind one page's issues. |
| compare_crawls | `base_session`, `compare_session` | Issues that are new, fixed and persisting between the two crawls. | "Did my changes help?" and "what regressed since the deploy?". Only new issues are regressions. |
| serp_preview | `urls` (at most 50), optional `engine` (google or bing) | For each URL, how its title and description will look in a search result: length, pixel width, truncation, Open Graph and Twitter Card fallbacks. | Rewriting titles and descriptions. It is about the snippet, not the page's other problems. |
| search_docs | optional `query`, `issue_key`, `max_results` (default 5, at most 10) | Matching sections of this documentation with their URLs, or the reference page for one issue key with its fix. With no arguments, the list of documentation pages. | Any question about bseoa itself. Its answer comes from these pages, not from a web search, and it works offline from a snapshot built into the binary. |
| account_status | nothing (hosted only) | Whether hosted is active, the page budget used and remaining, when it resets, retention, the licenses on the account, and a purchase menu with checkout links. | After a `trial_expired`, `no_hosted_addon` or `quota_exceeded` error, after paying, or to ask what the plan includes. |

## Limits

- A crawl started by an assistant stops at **500 pages** unless `max_pages` says otherwise. On hosted the hard cap is **2,000 pages per crawl**, and a crawl never takes more pages than the account has left in its budget.
- `query_issues` returns at most **100 issues per call**; follow `next_offset` for more.
- `serp_preview` takes at most **50 URLs per call**.
- On hosted, `check_page`, `serp_preview`, `search_docs` and `account_status` are limited to **30 calls a minute** per account, and one crawl runs per account at a time; a second `start_crawl` waits in the queue.
- Hosted crawls fetch at most two requests a second from a site, obey robots.txt and refuse private, loopback and internal addresses.
- No tool returns page HTML. If the assistant needs the markup it fetches the URL itself.

## Issues, keys, categories and severity

Every finding is an issue in the `bseoa.issue/v1` shape: a stable `key` such as `metadata.missing_meta_description`, a `category` (the part of the key before the first dot), a `severity`, the affected `url`, a human `message`, a `fix_hint` and a `docs_url` pointing at the [technical SEO reference](https://www.blackseoanalyzer.com/en/technical-seo) page for that key.

**Severity** is `low`, `medium`, `high` or `critical`. It ranks the SEO impact of the issue, not how certain the detection is. Group fixes by key, not by URL: one template usually produces hundreds of rows of the same key.

**Categories** follow the analyzer that found the issue: `metadata`, `content`, `link`, `url`, `performance`, `web_vitals`, `mobile`, `security`, `structured_data`, `internationalization`, `javascript`, `accessibility`, `ai_readiness` and `external_link`. The [features page](https://www.blackseoanalyzer.com/en/features) describes each analyzer.

To learn what one key means and how to fix it, ask the assistant; it calls `search_docs` with the `issue_key` and reads the reference page.

## Hosted: page budget, retention and plans

Hosted crawls count pages against a **rolling 30-day page budget**. `check_page`, `serp_preview` and `search_docs` never count. When the budget is used up, tools answer `quota_exceeded` with the time it resets, and single-page checks keep working.

- **Trial**: the first hosted sign-in starts 14 days of hosted with a 5,000-page budget and 30-day retention. The free trial of bseoa itself is separate and covers everything local.
- **Hosted plan**: 25,000 pages per rolling 30 days and 90-day retention, either way. The **hosted add-on** is $15 a month or $120 a year for anyone who owns a Single or Agency License; **hosted only**, without a license, is $50 a month or $500 a year.
- **Extended history**: keeps sessions for a year instead of 90 days.

**Retention** counts from the last time a session was read, so a crawl you keep coming back to stays. `account_status` reports the live numbers for your account and a checkout link for each plan it can buy; the lifetime [Single and Agency licenses](https://www.blackseoanalyzer.com/en/pricing) keep covering everything local.

## Errors

A tool that cannot do its job returns `{"error": "<code>", "message": "..."}`, often with an `instruction` for the assistant and a link. These are the codes.

| Code | Means | What to do |
| --- | --- | --- |
| no_license | Local: bseoa has no active license or the trial ended. | Start the [free 14-day trial](https://www.blackseoanalyzer.com/en/free-trial) or buy a license, store the key with `bseoa license store <key>`, restart the MCP server. |
| trial_expired | Hosted: the trial's hosted access has ended. | Follow the `checkout_url` in the error for a hosted plan, then call `account_status` and retry. Local use with a license key is unaffected. |
| no_hosted_addon | Hosted: the account has no hosted plan. | Same as above: the `checkout_url` is already the right product for the account. |
| quota_exceeded | Hosted: the rolling 30-day page budget is used up. | Wait for `resets_at`, or keep using `check_page`, which does not count. |
| rate_limited | Hosted: more than 30 calls a minute to a fetching tool. | Retry after `retry_after_seconds`. |
| blocked_target | Hosted: the URL points at a private or internal address, or its owner has asked not to be crawled by the hosted connector. | Audit it locally with the bseoa CLI. |
| not_available_hosted | Hosted: `spa: true` was requested; hosted does not render JavaScript. | Run the crawl locally with `--spa`, or crawl without rendering. |
| insufficient_scope | Hosted: the connector's token lacks `audit:write` (for `check_page` and `start_crawl`) or `audit:read`. | Sign in to the connector again and grant the access it asks for. |
| too_many_running_crawls | A crawl is already running for this database (local) or this account (hosted). | Poll `crawl_status` with the running job's id and start the next crawl when it finishes. |
| invalid_argument | A parameter was out of range: an empty URL list, more than 50 URLs, an unknown severity. | Read the `message`; it names the limit. |
| unknown_issue_key | `search_docs` was given an `issue_key` that bseoa does not emit. | Copy the `key` field from an issue exactly, including its category prefix. |
| database_error | The crawl database could not be opened or read. | Local: check `--db-path` is an absolute path the server can write. Hosted: try again shortly; if it persists, write to [hello@blackseoanalyzer.com](mailto:hello@blackseoanalyzer.com). |

## Where your data lives

**Local**: everything is in the SQLite database you name with `--db-path`. Pass the same absolute path to every host and every CLI command so they read the same crawls. Nothing leaves your machine except the requests the crawler makes to the site being audited and, if you enable them, calls to the AI provider you configured with your own key.

**Hosted**: one crawl database per account on our servers. Sessions are deleted when their retention has passed since they were last read. Tool results never include page HTML, and hosted stores the page source only for the analysis, never for display.

## Asking questions about bseoa

Ask the assistant in plain words: "does hosted render JavaScript?", "how do I cap a crawl at 200 pages?", "what does `link.broken_internal_link` mean?". It calls `search_docs` and answers from these pages with a link.

From a terminal, `bseoa docs "how do I crawl from a sitemap"` searches the same documentation, `bseoa docs --issue <key>` fetches one issue's reference page, and `--offline` uses the snapshot built into the binary.

For your own tooling: [/llms.txt](https://www.blackseoanalyzer.com/llms.txt) indexes the documentation, [/llms-full.txt](https://www.blackseoanalyzer.com/llms-full.txt) is the full text of the core pages as markdown, and any public page is available as markdown by adding `.md` to its URL.

```json
{"@context":"https://schema.org","@graph":[{"@type":"Organization","@id":"https://www.blackseoanalyzer.com/#organization","name":"Fiscus Technology, LLC","url":"https://www.blackseoanalyzer.com/","logo":"https://www.blackseoanalyzer.com/static/images/black-seo-analyzer.png","sameAs":["https://github.com/sethblack/black-seo-analyzer","https://www.youtube.com/@SethBlack","https://linkedin.com/in/seth-black-tx"],"founder":{"@type":"Person","@id":"https://www.blackseoanalyzer.com/#seth","name":"Seth Black","url":"https://www.blackseoanalyzer.com/about"}},{"@type":"WebSite","@id":"https://www.blackseoanalyzer.com/#website","name":"bseoa","url":"https://www.blackseoanalyzer.com/","publisher":{"@id":"https://www.blackseoanalyzer.com/#organization"}},{"@type":"WebPage","@id":"https://www.blackseoanalyzer.com/en/connector-reference","url":"https://www.blackseoanalyzer.com/en/connector-reference","name":"Connector reference - bseoa | Tools, limits and errors","description":"How the bseoa connector works: every tool with its inputs and outputs, crawl limits, the page budget and retention on hosted, what each error code means and what to do about it.","inLanguage":"en-US","isPartOf":{"@id":"https://www.blackseoanalyzer.com/#website"}},{"@type":"BreadcrumbList","itemListElement":[{"@type":"ListItem","position":1,"name":"Home","item":"https://www.blackseoanalyzer.com/"},{"@type":"ListItem","position":2,"name":"Connector reference","item":"https://www.blackseoanalyzer.com/en/connector-reference"}]}]}
```