Black SEO Analyzer

Report this account's hosted status live: whether hosted audits are active, the page budget used and remaining in the rolling 30 days and when it resets, how long crawl sessions are kept, the licenses on the account, and a purchase menu with a checkout link for each product the account does not already have (hosted monthly or yearly, priced for whether the account owns a license; extended history; lifetime license). Call it when a tool returned trial_expired, no_hosted_addon or quota_exceeded, after the user says they have paid, or when they ask what their plan includes.

account_status

Audit one URL immediately and return its SEO issues (schema bseoa.issue/v1: key, category, severity, message, fix_hint, docs_url). This is the fast path and the right first call for "what is wrong with this page?" - it fetches a single page and never follows links. Prefer it over start_crawl whenever the user asked about one specific page rather than a whole site, and that includes a site's homepage or bare domain ("check https://example.com/ for SEO problems") when the user did not ask for a crawl, a site audit or a number of pages. Does not count against the account's page budget; limited to 30 calls a minute. JavaScript rendering (spa) is not available on the hosted connector.

check_page

Compare two crawls of the same site and report which issues are new in the later crawl, which were fixed, and how many persist. Use it to answer "did my changes help?" or "what regressed since the last deploy?", and to gate a release: only the new_issues list represents a regression, so a pre-existing backlog never counts against a change. Get both session ids from list_crawls; base_session is the earlier crawl.

compare_crawls

Report the progress of a crawl started by start_crawl: state ("queued", "running", "finished" or "failed"), the crawl session_id to read results from, the pages stored so far, and the error text if it failed. Poll every few seconds; a queued crawl starts as soon as the worker is free. Do not call issues_summary or query_issues for that crawl until state is "finished", or you will read a partial result.

crawl_status

Summarize a crawl: total issue count, counts by severity and by category, and every distinct issue key with how many pages it affects plus up to five example URLs. Always call this before query_issues - it is small, it tells you which keys are worth drilling into, and it is what you should base a prioritized fix plan on. Omit session_id to summarize the account's most recent crawl.

issues_summary

List the crawl sessions stored for this account, newest last, with their session_id, start URL, start and end times, and page count. Single-page checks made with check_page are not crawls and are not listed. Call this first when the user refers to "the last crawl" or when you need a session_id for issues_summary, query_issues, page_report or compare_crawls. A session with no end time is still running or was interrupted.

list_crawls

Report everything recorded about one crawled URL: status code, redirect target, title and meta description, Open Graph tags, word count, link and asset counts, headings, TTFB, Web Vitals score, and the full issue list for that page. Use it after query_issues or issues_summary when you need the context behind a specific page's issues. It never returns the page's HTML source; to inspect markup, fetch the URL yourself.

page_report

List individual issues from a crawl, filtered by severity, issue key, category or URL prefix, as bseoa.issue/v1 records with the affected URL, the localized message, a fix hint and a docs link. Returns at most 100 issues per call: when the response has a non-null next_offset there are more, so call again with offset set to that value. Narrow with min_severity or key from issues_summary rather than paging through everything.

query_issues

Fetch each URL and report how its title and meta description will look in a search result: character length, pixel width, whether the engine will truncate it, and the Open Graph and Twitter Card fallbacks. Use it when the user asks how a page "looks in Google" or is rewriting titles and descriptions - it is about the snippet, not the page's other SEO problems, which check_page covers. At most 50 URLs per call; does not count against the page budget; limited to 30 calls a minute.

serp_preview

Search Black SEO Analyzer's own documentation and return the matching sections with their URLs. Use it for questions about bseoa itself: what a tool, command, flag or setting does, crawl limits and the page budget, pricing, licenses and the hosted plan, installing or configuring the CLI, GUI or connector, or what an issue key means (pass issue_key for that issue's reference page with its fix). Pass query for a question, issue_key for one issue, or neither to list the documentation pages. Works whatever the account's hosted status; does not count against the page budget; limited to 30 calls a minute.

search_docs