Skip to content

Open-source agentic AI Search Execution Platform. Track AI visibility, find opportunities, and let agents turn signals into prioritized actions and drafted fixes across ChatGPT, Claude, Gemini, Google AI Overviews, Google AI Mode, Perplexity, Grok, and Microsoft Copilot.

docs(billing): say what a workspace whose plan has ended can still do, and how the API, webhooks and MCP answer it (#1631)

Cihan25f0b49d20c1
diff --git a/docs/api-reference/webhooks.mdx b/docs/api-reference/webhooks.mdx
index 58faf38ce..5512838b8 100644
--- a/docs/api-reference/webhooks.mdx
+++ b/docs/api-reference/webhooks.mdx
@@ -303,6 +303,30 @@ The test uses the URL and secret currently in the form, so you can check an endp
- A single page is sent while the person waits. A bulk send (up to 25 pages) goes on in the background, one page after another, with a 2-second pause between pages.
- A workspace can send 200 pages in 24 hours.
+## When the plan has ended
+
+On Ansvisor Cloud, a workspace without an active plan is read-only: a cancelled plan or free trial reached its end, or a payment failed. See [What happens when my plan ends?](/faq).
+
+- **Nothing is sent.** Sending an opportunity, a task or a page, and **Test Webhook**, are writes, so the API refuses them with the 402 below. No Daily Pulse is generated.
+- **Callbacks store nothing.** Both callbacks (`/webhooks/content/{id}/status` and `/webhooks/content-drafts/{deliveryId}/status`) check the secret first, so a wrong one still answers 401. With the right secret, they answer `202` with this body and change nothing, whatever you sent:
+
+ ```json
+ { "success": false, "ignored": true, "code": "subscription_inactive" }
+ ```
+
+ It's a 2xx, so your workflow doesn't fail. Don't retry it.
+
+A write to the API (`/api/…`, any method but `GET`, `HEAD` and `OPTIONS`) from a person in a read-only workspace answers `402`:
+
+| Field | Value |
+|---|---|
+| `success` | `false` |
+| `error` | `plan_limit` |
+| `code` | `subscription_inactive` |
+| `message` | `Your plan has ended. Choose a plan to use Ansvisor again.` |
+
+A few writes stay open, such as disconnecting an outside account; the FAQ lists them. A self-hosted install is never read-only.
+
<Card title="Help center" icon="circle-question" href="/faq">
Common questions and troubleshooting.
</Card>
diff --git a/docs/faq.mdx b/docs/faq.mdx
index cd25b328d..8c6432044 100644
--- a/docs/faq.mdx
+++ b/docs/faq.mdx
@@ -14,6 +14,21 @@ description: "Common questions about Ansvisor."
Rough back-of-envelope: a brand tracking 30 prompts daily across 4 AI engines costs ~$5–15/month in API fees, depending on response length and provider mix.
</Accordion>
+ <Accordion title="What happens when my plan ends?">
+ On Ansvisor Cloud, a workspace becomes **read-only** when a cancelled plan or free trial reaches its end, or when a payment fails (the first charge after the trial too), until the payment method is updated. Everything you set up stays.
+
+ The 14-day free trial starts with a card at checkout, and the plan starts on day 15: a trial that simply ends becomes a paid plan. Cancelling in **Billing**, during the trial or after it, keeps the workspace working until the last day of the trial or of the period you paid for.
+
+ While it's read-only:
+
+ - Everyone can still sign in, open every page and read everything.
+ - Adding, running, writing and AI open a dialog: **Choose a plan to keep going**, or **Update your payment method to keep going** after a failed payment. Admins choose a plan or update the payment method from it; other members are asked to turn to an admin.
+ - These still work: **Billing** and choosing a plan, your own profile and signing out; stopping a tracking job that is running and stopping the Content Agent; disconnecting Search Console, Analytics, Webflow, an AI-bot log or a store; removing your own AI provider key; deleting an Agent Chat conversation; deleting API keys, removing members, revoking invitations and accepting an invitation; creating API keys (the [MCP server](/guides/mcp-server) only reads for this workspace); and deleting a brand.
+ - Nothing runs on its own: no tracking, scraping or AI, no agents, no syncs with outside services, no new signals, actions or suggestions. AI-bot logs, the tracking snippet's visits and [webhook](/api-reference/webhooks) callbacks are answered but not stored.
+
+ Once an admin chooses a plan, the workspace works as before. Self-hosted installs are never read-only. Setup is unchanged: a new workspace that has never had a plan goes through setup and its plan step as before. Setup suggests its topics, prompts and competitors with three suggestion requests, and a workspace can make 20 suggestion requests a day in all.
+ </Accordion>
+
<Accordion title="Why don't you scrape ChatGPT/Gemini directly?">
For programmable AI engines (OpenAI, Anthropic, Google Gemini API), Ansvisor uses official APIs — most reliable, well-priced, and TOS-compliant. For *web* AI engines that don't have public APIs (like ChatGPT.com search results), Ansvisor uses Cloro as a managed scraping backend. Cloro handles browser fingerprinting, captcha bypass, and rate-limiting at scale.
diff --git a/docs/guides/ai-traffic-analytics.mdx b/docs/guides/ai-traffic-analytics.mdx
index b5a846531..565161290 100644
--- a/docs/guides/ai-traffic-analytics.mdx
+++ b/docs/guides/ai-traffic-analytics.mdx
@@ -20,6 +20,8 @@ The **AI Traffic Analytics** page (`/dashboard/traffic`, **AI Referral Traffic**
A section whose source isn't connected stays on the page with a **Needs …** tag and a **Connect** button, rather than hiding. Only admins and managers can connect a source.
+On Ansvisor Cloud, while the workspace's plan has ended ([read-only](/faq)), the snippet and your AI-bot connections are answered but nothing is stored, so your site keeps working and the sender doesn't retry: a beacon to `POST /track/{trackingCode}` gets `204`, and `POST /bots/ingest` gets `200` with `{ "received": 0, "verified": 0, "stored": 0, "inactive": true }`.
+
## Setup
<Steps>
diff --git a/docs/guides/mcp-server.mdx b/docs/guides/mcp-server.mdx
index 248aed086..37d22091b 100644
--- a/docs/guides/mcp-server.mdx
+++ b/docs/guides/mcp-server.mdx
@@ -367,6 +367,31 @@ Ask your client things like:
The model picks the right tool, fills in the brand id and filters, and
answers in plain English using the returned data.
+## When the plan has ended
+
+On Ansvisor Cloud, a workspace without an active plan is read-only (see
+[What happens when my plan ends?](/faq)). Its API keys keep working for
+reading:
+
+- `list_` and `get_` tools run as usual.
+- Every other tool (each one marked **writes** above) is refused before it
+ runs. The call fails with this text:
+
+ ```json
+ {
+ "error": "plan_limit",
+ "code": "subscription_inactive",
+ "message": "This workspace's plan isn't active (its free trial ended or it was canceled), so it is read-only: reading still works, but nothing can be changed, run or generated until an admin chooses a plan in Settings › Billing."
+ }
+ ```
+
+- The REST routes under `/api/mcp/…` answer a `POST`, `PUT`, `PATCH` or
+ `DELETE` with `402` and the same body.
+
+Retrying doesn't help: an admin has to choose a plan first. New API keys
+can still be created; on a read-only workspace they only read. A self-hosted
+instance is never read-only.
+
## Revoking access
If a key leaks or you stop using a client, open **Settings → API Keys** and
diff --git a/skills/ansvisor-aeo-coach-standalone/SKILL.md b/skills/ansvisor-aeo-coach-standalone/SKILL.md
index 580cae48a..4a68b50e0 100644
--- a/skills/ansvisor-aeo-coach-standalone/SKILL.md
+++ b/skills/ansvisor-aeo-coach-standalone/SKILL.md
@@ -568,6 +568,11 @@ When the user asks how AI describes the brand, why sentiment moved
- `404 ... not found` → the id doesn't belong to the authenticated
user's organization. Re-run `GET /brands` (or the matching list
endpoint) to get the right id.
+- `402` with `"code": "subscription_inactive"` → the workspace's plan
+ has ended (trial over, plan cancelled or payment failed) and it is
+ read-only: `GET` endpoints still work, writes are refused. Tell the
+ user their plan has ended and that an admin can choose a plan (or
+ update the payment method) in **Settings → Billing**. Don't retry.
- `500` with a message (e.g. a plan limit, "Generate suggestions for
this range first") → relay the message as is.
- Network timeout → retry once. If it still fails, surface it and stop.
diff --git a/skills/ansvisor-aeo-coach/SKILL.md b/skills/ansvisor-aeo-coach/SKILL.md
index 54912e354..b9e17fe57 100644
--- a/skills/ansvisor-aeo-coach/SKILL.md
+++ b/skills/ansvisor-aeo-coach/SKILL.md
@@ -366,6 +366,13 @@ an LLM. Call one **only** when the user asked for that specific change
"to be helpful". Say what you are about to do in one line first. The
change is logged under the API key's user.
+If a tool fails with `"code": "subscription_inactive"`, the workspace's
+plan has ended (trial over, plan cancelled or payment failed) and it is
+read-only: `list_` and `get_` tools still work, every other tool is
+refused. Tell the user their plan has ended and that an admin can choose
+a plan (or update the payment method) in **Settings → Billing**. Don't
+retry, and don't try another write tool instead.
+
## Core workflows
### 1. Brand snapshot ("how am I doing?")