# Serpkin docs: full text > Every Serpkin docs page in one file, for AI assistants and coding agents. > Canonical index: https://serpkin.com/docs > Machine-readable index: https://serpkin.com/docs-agent.json > Generated from the same content as the website. Use the canonical page when linking to a person. --- # Getting started with Serpkin > From nothing to your first verified SEO mission: one command, your coding agent, and a check that proves the change worked. Canonical: https://serpkin.com/docs/getting-started Updated: 2026-11-03 | 5 min read ## In short - Run npx serpkin in your website's repository: it signs you in, connects your agent, registers the site and uploads a route map. - Ask your agent "What should I do for SEO?" or run /serpkin:next in Claude Code to get the top mission. - Check the preview with npx serpkin check, deploy as usual, then verify the mission in production. - Serpkin measures the result at 14 and 28 days against similar pages you didn't change. Serpkin gives your coding agent one SEO mission at a time: the change worth making next on your site, with the target pages, mapped source files where available, and checks that verify the change. This page takes you from nothing to your first verified mission. For agent setup, you need a website repository, Node 22 or newer, and Claude Code, Codex or Cursor. A public site or deployed preview is needed for scanning; localhost cannot be scanned. You can also start with a website audit in the app. Using Hermes, Grok Bot or an agent that manages work outside a repository? Start with [Connect AI agents](https://serpkin.com/docs/ai-agents). Add a website in the app, choose read-only monitoring access and let the agent discover sites through `serpkin_get_workspace`. You can connect a coding agent later for implementation. The project-native setup below remains available. ## Connect your project and review your first findings 1. **Run the setup command in your website's repository** ``` npx serpkin ``` _Terminal_ It opens `serpkin.com/cli` in your browser with a short code such as `BCDF-GHJK`. Check that it matches your terminal and approve. That creates an agent key named "Serpkin CLI on your machine". The key is saved outside your repository, and you can revoke it any time in Agents. 2. **Let it detect your framework and connect your agent** The CLI detects Next.js (App and Pages Router) fully, and Astro, SvelteKit, Nuxt and Remix as best effort. In a monorepo it asks which app is the website. Then it connects the agents it finds: for Claude Code it offers the Serpkin plugin, for Cursor it writes `.cursor/mcp.json` and a project rule, and for Codex it adds the server to `~/.codex/config.toml` and a short section to `AGENTS.md`. 3. **Register the site and prove you own it** The CLI registers your site and uploads a route map: a list of URL paths and the source files that render them, so missions can name the files to change. Your source code isn't uploaded. To unlock full scans (on a trial or a plan), prove ownership with Google Search Console or by deploying `public/serpkin-verification.txt` and running `npx serpkin verify`. 4. **Ask your agent for the first mission** Missions need a plan. If you have not started one, the agent gets the error code `TRIAL_REQUIRED` with a link: start a 7-day free trial of Builder or Pro (card required, no charge until day 8), then ask again. Without a plan you can still see the preview audit of up to 6 pages. In Claude Code, run `/serpkin:next` in a new session. In any agent, ask: *"What should I do for SEO?"* The agent calls Serpkin, gets the top mission and starts working on it. 5. **Ship it, then verify** Your agent makes the change in your repository. Check the preview deploy with `npx serpkin check ` (or `/serpkin:ship ` in Claude Code), merge and deploy as you normally do, and ask the agent to verify the mission in production. The audit reads public page content, records existing pages and technical findings, and builds a business brief with sources. Review or correct the product, audience, features, relevant topics and exclusions under Site. Content missions need a complete scan, a specific business fit and supporting demand. Failed or partial audits keep previous findings and distinguish retryable errors from capacity and rendering limits. No worthwhile recommendations is a valid result. ## Review your site audit The audit leads with what Serpkin understood about the product, observed technical findings and existing pages. It does not estimate traffic gains. Missions stays focused on the first recommendation; other findings and research are available under Explore. If no worthwhile change is supported, the app says so. Site audit brings the business summary, page coverage and technical findings into one view. The coverage bar compares checked pages with discovered pages; it is not an SEO score. Open a technical finding to see its recorded source pages, or choose Correct business context to update the brief. Missing coverage and check results stay explicit. If the business description and audience are known, a context review asks for one specific customer problem or lets you confirm suggested topics. You can open the full brief to correct details. When you add a site in the web app you can run one first keyword research (2 credits, once) as soon as the audit is ready; it is ticked by default and you can untick it. Monthly automatic research is off by default: turn it on in Site details, or pass `--auto-research` for a new CLI site. Already queued jobs continue. After the free preview, connect Google Search Console from the Site page. It verifies that you own the site, unlocks the full audit, and shows the searches your pages already appear in, which a new site rarely gets from any other source. Your first mission says so when it is the best next step. Registration queues the first audit on the server. It reads public page content, checks technical health, records existing pages and builds a sourced business brief. Open **Site → Site audit** to review what the product does, who it serves, relevant search topics and exclusions. Problems and features are optional extra context. Your source code stays in your repository. _Audit states and the next useful action_ | What you see | What to do | | --- | --- | | Audit queued or running | Leave it running; the app refreshes automatically. You can leave the page. | | Preview audit | Verify site ownership, then run the full audit. Preview scope is the homepage and up to five linked pages. | | Review business brief | Check the product, audience and specific topics, then confirm. Your corrections take precedence. | | Crawl limit reached | Keep the checked-page findings. Compare crawl limits with discovered pages; an identical scan does not increase capacity. | | Unreadable JavaScript content | Provide main content in server HTML or review rendering support before retrying. | | Temporary fetch failure | Resolve reachability or access errors, then retry when scans are available. | | Audit ready, no mission | No sufficiently supported change is ready. An empty queue is a valid result. | New content, tools, comparison pages and expansions need complete coverage, specific business fit and positive demand evidence. Existing content is checked first. A partial scan keeps previous findings and started work; it cannot establish that an old issue has disappeared. See [Missions](https://serpkin.com/docs/missions) and [Troubleshooting](https://serpkin.com/docs/troubleshooting). ## What you see in the terminal Setup prints one line per step. Adding a site automatically queues its first audit. The CLI waits for the scan and shows your first mission before it finishes, usually in under a minute. An illustrative run on a Next.js site: ``` $ npx serpkin ✓ Signed in. Key saved to ~/.config/serpkin/credentials.json (outside this repo) ✓ Next.js (app router): 14 routes ✓ Claude Code: installed the Serpkin plugin. Try /serpkin:next in a new session. ✓ Site registered: https://acme.dev (.serpkin.json saved; it holds no secrets) ✓ Route map uploaded. Missions can now name the files to change. Scanning your site for the first missions (usually under a minute)… ✓ 6 missions ready for acme.dev. First mission: Remove unintended noindex from public pages ``` _Terminal (illustrative)_ If the scan is still running when the CLI finishes, it says so; your agent sees the missions as soon as the scan is done. Re-running `npx serpkin` is safe: it reuses the stored key and site, and only refreshes its own blocks in agent config files. ## Your first mission On a new site, the first missions are usually foundation fixes from the scan: pages Google can't index, a missing sitemap, broken titles or canonicals. Each mission says what it's based on, why it comes now, which files to edit and how Serpkin will check it. Search data and Search Console add growth missions later, such as pages close to page one or topics your site doesn't cover. See [Missions](https://serpkin.com/docs/missions) for the full list. _What changes as Serpkin learns more about your site_ | Your site | Where missions come from | How results are measured | | --- | --- | --- | | Brand new, nothing connected | The site scan: foundation and technical fixes | Verification checks on the live page | | Ranking, no Search Console | The scan plus Serpkin's own search data and estimated rankings | Rank checks at 14 and 28 days | | Search Console connected | The scan plus your real queries, clicks and pages | Your own clicks and impressions at 14 and 28 days | > **Connect Search Console when you can** > > It's optional and read-only, but it gives Serpkin your real queries and clicks, which makes missions more specific and results more reliable. Connect it from the Site page in the app. ## Ship and verify Verification is how a mission gets marked done. Serpkin checks the change itself, on the environment you name: - **Preview:** before you merge, Serpkin checks the preview deploy against the mission's acceptance checks. - **Production:** after you deploy, Serpkin checks the live site. A passed production check marks the mission verified and starts the result measurement. - **Results:** Serpkin takes a baseline and measures again at 14 and 28 days, compared with similar pages you didn't change. `npx serpkin check ` is a separate safety net. It compares a whole preview with production and exits with code 1 when the preview would hurt SEO, for example a new `noindex`, a removed title or canonical, or a broken sitemap. You can run it in CI on every pull request; see [Serpkin in GitHub Actions](https://serpkin.com/integrations/github-actions). ## Where to go next The workspace has five main destinations: Missions for the next useful change, Results for recorded progress, Site for audits and monitoring, Agents for connections and permissions, and Account for usage and billing. Site and Account have section shortcuts. Mission details show recorded work stages; a copied brief is not a started mission. ### Learn how it works - [Missions](https://serpkin.com/docs/missions): the types, how they're ranked and how to dismiss one. - [Verification and results](https://serpkin.com/docs/verification-and-results): what passes, and how impact is measured. - [Site watch](https://serpkin.com/docs/site-watch): the regular recheck and the alerts it sends. ### Set up your agent in depth - [Claude Code](https://serpkin.com/integrations/claude-code), [Cursor](https://serpkin.com/integrations/cursor)or [Codex](https://serpkin.com/integrations/codex). - [Weekly pull requests](https://serpkin.com/docs/weekly-pull-requests): let Claude Code work on the top mission every Monday. Stuck? [Troubleshooting](https://serpkin.com/docs/troubleshooting) covers sign-in, agents that don't see Serpkin and verifications that fail. ## Questions ### What should I do after my first verified mission? Review the verification in Results and give search performance time to change. Missions, scans and site watch continue while you have a trial or a plan; if you cancel, your data stays readable. On return visits, Your SEO week summarizes recorded activity and the next eligible mission; it is not a fresh scan and may correctly have no new recommendation. ### Why is the scan finished but there is no content mission? Content recommendations require complete coverage, a specific business fit and demand evidence. Verify ownership after a preview, review the business brief when asked, and address incomplete coverage before retrying. Zero worthwhile recommendations is valid. ### Do I need Search Console to start? No. A new site starts with missions from the site scan. Search Console is optional and read-only; connecting it adds missions from your real queries and makes results more reliable. ### Does Serpkin change my code? No. Your coding agent makes every change in your repository, and you review, merge and deploy it. Serpkin receives a map of URL paths to file names, not your source code. ### What if my site isn't live yet? Serpkin needs a public URL to scan. Use a preview deploy with npx serpkin --url , not localhost. ## Related - [Missions: what they are and how they're ranked](https://serpkin.com/docs/missions): Missions - [Verification and results](https://serpkin.com/docs/verification-and-results): Verification and results - [SEO for Claude Code](https://serpkin.com/integrations/claude-code): Claude Code - [Troubleshooting: setup, scans, verification and weekly runs](https://serpkin.com/docs/troubleshooting): Troubleshooting --- # Connect AI agents > Connect once, choose what the agent may do, and start with your site's actual findings. A repository is optional for monitoring and planning. Canonical: https://serpkin.com/docs/ai-agents Updated: 2026-10-30 | 7 min read ## In short - Monitoring and prioritization do not require a repository. - Use separate keys for monitoring, research and implementation. - A handoff prepares work; it does not dispatch an agent. - A configured client still needs a successful authenticated tool call. Connect an agent to review SEO, investigate a supported opportunity or implement a mission. You do not need a repository just to read findings. Start by adding your public website in the app, then open Agents from the workspace connection link. Choose the client and the access it needs. Serpkin uses the same authenticated MCP endpoint for every client; client names change the setup instructions, not the evidence behind recommendations. ## Choose access _Agent key permissions_ | Access | Allowed work | | --- | --- | | Monitor only | Discover sites, read audits and results, prepare delegation briefs. No research, edits to mission status or job cancellation. | | Research | Monitor plus scans, keyword research, saved research organization and tracking. No implementation submission or verification. | | Implement | Monitor plus mission status updates, result submissions, verification and preview checks. No paid research. | | Full access | Combines research and implementation, including site registration. Account, billing and credential controls still require the owner. | Create a separate key for each role. Research and full-access keys can have an additional monthly credit ceiling. Queued and running research reserves credits against it; settled work counts its charged credits. The ceiling resets with the UTC calendar month and never adds to your workspace allowance. A zero ceiling prevents credited research. Blank means there is no extra key ceiling. Existing keys and CLI device-login keys retain full access unless the owner changes them. Site-level schedules and automatic topic research are separate workspace activity, not jobs started by a particular key. A key ceiling does not cap that activity, model spending or the number of free reads. Review the site's automatic-research setting separately. Changing or revoking a key affects new requests; already accepted jobs continue. The owner can edit access and ceilings in Agents without sharing credentials with the agent. ## Hermes Merge the following into the active Hermes profile's configuration, normally `~/.hermes/config.yaml`. Preserve existing servers. Put the real key in the profile's private environment or its process environment. Hermes supports environment references in headers; Serpkin does not require an AI-provider key for the connection. ``` mcp_servers: serpkin: url: "https://serpkin.com/api/mcp" headers: Authorization: "Bearer ${SERPKIN_API_KEY}" ``` _~/.hermes/config.yaml_ Reload MCP or restart the Hermes session, then ask it to call `serpkin_get_workspace`. A valid authenticated response is the connection check. A configuration entry alone is not proof that the key resolved or that the server is reachable. For CLI-assisted configuration, use `npx serpkin --connect-only --agent hermes`. The CLI writes a new configuration file but leaves a nonempty existing file untouched and prints the entry to merge. ## Grok Bot In Grok Bot's app connections, add a custom MCP server using `https://serpkin.com/api/mcp`. Supply a Serpkin key through protected bearer-header settings where the current connector supports them. Do not paste the key into a Bot conversation. The public Grok Bot documentation describes custom MCP connections, but its live static-key sign-in flow has not been exercised here. This is a manual connection path, not a listed marketplace plugin or a claim of native certification. Grok Bot runs on its own computer. A localhost Serpkin URL on your laptop will not refer to that server from the Bot. Use a reachable HTTPS deployment and honor your team's connection policy. Grok Build is a separate coding product with its own MCP configuration; do not substitute its terminal commands for the Bot's connector settings. ## Other MCP clients Choose a Streamable HTTP connection and send `Authorization: Bearer ` on each request. Environment syntax and secret storage differ by client. Serpkin currently uses static agent keys rather than an MCP OAuth consent server. A client that only offers OAuth cannot be assumed compatible. Inspect its supported authentication options before creating a connection. ``` Call serpkin_get_workspace. Show the available sites and my key's access. Ask which site I mean if the choice is ambiguous. ``` _First request_ The connection supplies the workspace id. Existing clients may still pass `project_id` explicitly; a different workspace id is rejected. Discovery is paginated, so follow `next_cursor` when the chosen site is not on the first page. Tools-only clients do not need MCP resources, slash commands or a local `.serpkin.json`. A read-only response should never be presented as permission to start work. ## Delegate and follow work Read `serpkin_weekly_summary` and `serpkin_next_mission` for the chosen site. To delegate, fetch `serpkin_get_handoff` with the mission id. It returns current site context, mission data, implementation and verification requirements, a revision and status-reading tools. It does not contact another agent, reserve a worker or mark a task as started. Use a channel you have authorized to pass the brief to an implementation agent with its own appropriate key. Do not include keys in the brief. The receiving agent re-fetches it before editing, checks the revision and status, and stops if work is already complete or no longer relevant. It records acceptance with `serpkin_update_mission`, submits its actual artifacts and requests verification. The planning agent reads mission history to follow progress. A human still reviews and deploys; later search movement remains correlation. ## When connection or work is blocked A 401 usually means a missing, unresolved or revoked key. An access-denied result means the operation needs a different role, not a new retry loop. An agent-budget error means credits are charged or reserved against this key's ceiling. Inspect queued work and ask the owner before changing it. A crawl-limit or rendering warning needs a change in coverage conditions before another identical scan can help. The owner can inspect the same evidence in the app and revoke an unused connection at any time. For project-native setup use the [CLI reference](https://serpkin.com/docs/cli). For a worked management routine read [SEO with AI agents](https://serpkin.com/guides/seo-with-ai-agents). Connection examples are based on published client interfaces and Serpkin protocol tests; they do not establish every client version's end-to-end behavior. ## Related - [Getting started with Serpkin](https://serpkin.com/docs/getting-started): Getting started - [MCP tools and prompts reference](https://serpkin.com/docs/mcp-tools): MCP tools - [Credits: what research costs and how the monthly allowance works](https://serpkin.com/docs/credits): Credits - [Manage SEO with AI agents](https://serpkin.com/guides/seo-with-ai-agents): SEO with AI agents --- # Missions: what they are and how they're ranked > One SEO task for one site, with the evidence, the files to change and the checks that prove it worked. Here is how missions are built, ranked and closed. Canonical: https://serpkin.com/docs/missions Updated: 2026-11-03 | 6 min read ## In short - A mission is one task: what to change and why now, the target pages and files, steps for your framework, and the checks Serpkin runs. - Missions fall into three groups: fix what's broken, win more searches, and get found elsewhere. - The queue puts work in progress first, then fixes that block indexing, then the highest rule-based priority score. - Dismiss a mission with a reason; two "not relevant" or "disagree" dismissals of one growth kind rank that kind lower. - New missions per month: 30 on Builder and 150 on Pro, including during the 7-day free trial. Without a plan there are none. A planning agent can fetch `serpkin_get_handoff` to prepare a current, versioned implementation brief without starting work. Pass it through an authorized channel to an implementation-capable agent. That agent re-fetches the brief, checks status and revision, then records acceptance. Follow the original mission and history rather than creating a duplicate. No handoff tool dispatches an external agent or includes a credential. Before the first handoff, Missions focuses on one supported recommendation and a short audit conclusion. Open Other findings and activity or Explore research and reports for more. Copying a mission is a handoff, not execution; mark it in progress when work begins. A new mission consumes an allowance when created, not when started or completed. Source files depend on supported route mapping; target-page evidence stays available without it. A mission is one SEO task for one site: the change worth making next, why it matters now, the files to edit and the checks that prove it worked. Serpkin builds missions from your site scan, Search Console when it's connected, rankings, backlinks, AI answers and your competitors' new pages. Your coding agent picks them up over MCP, one at a time. This page explains the mission types, how they're ranked, what each status means and how to dismiss one. ## What a mission contains - **What and why:** a plain title, the evidence it's based on (a scan, Search Console, rankings or search data) and a one-line reason it comes now. - **Where:** the target pages and, from your route map, the source files that render them. - **How:** steps for your framework, with snippets for metadata, sitemaps, redirects or structured data where they apply. - **Done when:** acceptance checks that Serpkin runs itself when you verify the mission. Page text and search queries inside a mission come from the web, so they're marked as untrusted data. Agents connected to Serpkin are told to treat them as information, never as instructions. ## Mission types The app groups missions the same way, by what they get you: _Mission groups and common types_ | Group | Examples | What it gets you | | --- | --- | --- | | Fix what's broken | Pages that don't return 200, unintended noindex, missing sitemap or robots.txt, broken links, canonicals, Core Web Vitals, structured data, and "Fix the basics" | Google can crawl, index and understand every page | | Win more searches | Near page one, shown often but rarely clicked, pages competing for one query, declining pages, new pages, free tools and comparison pages | More of the searches people already make | | Get found elsewhere | Directory listings, backlinks to win back, sites that link to competitors, getting cited in Google's AI answers | Visitors, links and citations from other sites | Small page fixes, such as titles, meta descriptions, canonical URLs, H1 headings, link previews and structured data, ship together as one **Fix the basics** mission: several quick fixes in one change and one check. ### Where growth missions come from Which growth missions you get depends on the data your site has. A new site starts with foundation fixes from the scan. Keyword research (your first run is offered when you add the site) adds new-page and content missions for topics your site doesn't cover yet. With Search Console connected, missions also come from your real queries and clicks, including pages that are close to page one. Competitor watch, AI answer checks and backlink snapshots add their own missions on top. See [Competitor watch](https://serpkin.com/docs/competitor-watch). ### Business fit comes before queue size New pages, expansions, tools and comparisons require a complete site audit, positive demand evidence and a specific connection to the product and audience in your business brief. Each carries a business-fit explanation with source pages. A topic already covered by an existing page is skipped; partial coverage needs a concrete improvement. The priority score cannot make an unrelated topic qualify. The queue has no minimum size. Monthly discovery is optional and independent of how many missions are open. An empty queue is a supported result. Failed and incomplete audits preserve prior findings and started work; unsupported content ideas wait for review. Review your brief under **Site → Site audit**. ## How missions are ranked Your agent asks for the next mission, so the order matters. The queue is sorted by four rules, in this order: 1. **In progress** A mission you already started comes first, so work gets finished. 2. **Blocking** Fixes that stop Google from crawling or indexing the site. 3. **Priority score** A rule-based score from the data level, signal size, effort and confidence. 4. **Oldest first** Ties go to the mission that has waited longest. _The queue order: work in progress first, then anything blocking indexing, then the highest score_ The priority score is a ranking aid, not a traffic forecast. Each mission also carries a short "why now", for example "These queries already rank close to page one, and the page has specific gaps to fix." Your agent sees it with the mission. ## Statuses and lifecycle 1. **Ready** Found and waiting. Data refreshes update it in place. 2. **In progress** Your agent started it. Refreshes only flag that the data changed. 3. **Implemented** The change is submitted and waiting to be verified. 4. **Verified** Serpkin's checks passed on the environment you named. 5. **Measuring** A baseline is taken and results follow at 14 and 28 days. _A mission's path from discovery to a measured result_ _What each status means_ | Status | Meaning | | --- | --- | | Ready | Open and waiting for your agent. If the rule fires again with new data, the mission is refreshed in place. | | In progress | Started. Serpkin won't move the goalposts: new data only marks it as changed. | | Implemented, awaiting verification | The agent submitted the change; verification is pending or running. | | Failed | The last verification failed. Fix what the checks reported and verify again. | | Verified, then completed | Checks passed. After the 28-day measurement the mission is completed. | | Resolved | A complete refresh no longer supports the issue, or a complete audit found that a topic is unrelated or already covered. Incomplete scans do not resolve earlier findings. | | Dismissed | You chose not to do it. It stays hidden for 180 days unless you restore it. | A mission that was completed can come back as a new mission after 90 days if its rule fires again, so a problem that returns is caught. ## Dismissing a mission You or your agent can dismiss a mission, optionally with a reason: not relevant, already done, too much work, disagree or other, plus a short note. Restore it from the app at any time. > **Serpkin learns from dismissals** > > When a site dismisses two growth missions of the same kind as "not relevant" or "disagree", new and refreshed missions of that kind rank 15 points lower for that site. Foundation fixes are never lowered. ## Monthly mission limits Each plan includes a number of new missions per month: 30 on Builder ($29 a month) and 150 on Pro ($79 a month), and the same during the 7-day free trial. Without a plan, no missions are created. The count resets on the 1st (UTC). Missions that already exist keep refreshing when you reach the limit; only new ones wait. When you get close, the app and your agent say what the next plan includes. See [Plans and limits](https://serpkin.com/docs/plans-and-limits). ## Questions ### Why did a mission disappear? A complete refresh can resolve an issue that disappeared. A complete audit can also withdraw an unrelated or already-covered topic. Partial scans preserve earlier findings. You can bring it back from the app if you still want to do it. ### Can I do a mission that isn't first in the queue? Yes. Ask your agent for a specific mission, or start it from the app. The queue order is a recommendation, not a rule. ## Related - [Getting started with Serpkin](https://serpkin.com/docs/getting-started): Getting started - [Verification and results](https://serpkin.com/docs/verification-and-results): Verification and results - [Plans and limits](https://serpkin.com/docs/plans-and-limits): Plans and limits - [Competitor watch: what your competitors publish](https://serpkin.com/docs/competitor-watch): Competitor watch --- # Verification and results > How Serpkin checks that a change is right before and after you deploy, and how it measures what happened in search afterwards. Canonical: https://serpkin.com/docs/verification-and-results Updated: 2026-10-29 | 6 min read ## In short - Serpkin verifies a mission itself, on preview, production or evidence, against the mission's acceptance checks. - A verification passes only when every required check passes; failed checks say what they observed. - After a pass, Serpkin takes a baseline and measures at 14 and 28 days, then marks the mission completed. - Results compare your changed pages with similar pages you didn't change, and are labeled as correlation, not proof. Serpkin doesn't take your agent's word that a mission is done. Verification means Serpkin checks the change itself, on the environment you name, against the mission's acceptance checks. After a mission passes, Serpkin measures what happened in search at 14 and 28 days and compares it with similar pages you didn't change. This page explains both halves. ## The three verification environments _Where Serpkin checks a mission, and what passing means_ | Environment | What Serpkin checks | Passing means | | --- | --- | --- | | Preview | The mission's checks against your preview deploy URL, before you merge | The change is right on the preview (preview verified) | | Production | The same checks against your live site, after you deploy | The change is live and correct (production verified) | | Evidence | That the data behind the mission is still fresh, and for content and Search Console missions, the page checks on the live site | The work matches the evidence; used for content, research and link missions | Technical and foundation missions are usually verified on preview and then production. Content missions, such as a new page or a refresh, are verified with the evidence environment, which runs their page checks on the live site: for example that the page answers the questions from its brief, that its FAQ markup is valid, or that the links the mission asked for exist. ### How your agent asks for it Your agent submits the change with `serpkin_submit_result`, then calls `serpkin_verify_mission` with the environment. In Claude Code, `/serpkin:ship ` does the submit, the preview check and the preview verification in one step. You can also ask in plain words: ``` Verify the mission on production now that it's deployed. ``` _Ask your agent_ ## Pass, fail or incomplete Every check has an outcome, and the mission takes the combined result: Passed - ✓Good:Every required check passed on the environment - ✓Good:The mission is marked verified on that environment - ✓Good:A production pass starts the result measurement Failed or incomplete - ✕Problem:Failed: at least one check failed; each check says what it observed - ✕Problem:Incomplete: nothing failed, but a check couldn't run or needs a person - ·Fix what was reported and verify again; nothing is lost _A verification passes only when every required check passes; any failure fails it_ > **Previews behind deployment protection** > > If your previews require a login, Serpkin gets HTTP 401 or 403 and can't check them. Allow Serpkin through the protection (on Vercel, a protection bypass for automation) or verify on production. Preview hosts such as Vercel also add an `X-Robots-Tag: noindex` header to every preview; Serpkin treats that header as a preview artifact, not a regression. Workspaces can also require human editorial acceptance for content missions. When that setting is on, a content mission only passes evidence verification after someone has reviewed its acceptance criteria in the app. ## How results are measured The Results screen shows each mission’s baseline, 14-day check and 28-day check as recorded, unavailable or not recorded yet. When click counts are available, a bar comparison shows the recorded values alongside the measurement table. A missing value is not displayed as zero, and a preview check does not complete the production-verification stage. 1. **Verified** Production verified for technical fixes; evidence passed for content, links and research. 2. **Baseline** Clicks, impressions or positions for the target pages and queries, plus a control group. 3. **14 days** First measurement. The mission shows as measuring. 4. **28 days** Second measurement. The mission is completed. _After a mission passes, Serpkin takes a baseline and measures twice, against pages you didn't change_ With Search Console connected, Serpkin measures your own clicks and impressions. Without it, it uses rank checks on the mission's target queries. If neither is available, the result says measurement is unavailable rather than guessing. ### Compared with pages you didn't change Search moves for many reasons: seasons, Google updates, competitors. So Serpkin compares the change on your target pages with a control group: similar pages on the same site that you didn't touch, matched by their baseline impressions and position. When too few pages match, it compares with the rest of the site. The net effect is the target's change minus the control's change. _How to read a result_ | Field | What it means | | --- | --- | | Target change | How the mission's pages or queries moved between the baseline and this measurement | | Control change | How similar pages you didn't change moved over the same period | | Net effect | The target change minus the control change | | Confidence | Low, Medium or High, based on the size of the data, the control group and how noisy it is | ## Correlation, not proof A good net effect means the pages you changed did better than similar pages you didn't. It doesn't prove the change caused it, and a flat result doesn't mean the change was wrong: search impact can take longer than 28 days. Serpkin labels every result this way and never promises rankings or traffic. Use results to see which kinds of missions work on your site, not as a guarantee. Results appear on the Results page in the app, and verified missions show up in the weekly email. Your agent can read results with `serpkin_get_results`. See [Site watch](https://serpkin.com/docs/site-watch) for what Serpkin keeps checking after the measurement ends. ## Questions ### Why did verification fail on my preview? Most often the preview is behind deployment protection and returns HTTP 401 or 403. Allow Serpkin through it, or verify on production after you deploy. ### Can I verify again after a failure? Yes. Fix what the failed checks reported and run the verification again. The mission keeps its history. ## Related - [Missions: what they are and how they're ranked](https://serpkin.com/docs/missions): Missions - [Site watch: regular rechecks and alerts](https://serpkin.com/docs/site-watch): Site watch - [Troubleshooting: setup, scans, verification and weekly runs](https://serpkin.com/docs/troubleshooting): Troubleshooting - [SEO checks in GitHub Actions](https://serpkin.com/integrations/github-actions): GitHub Actions --- # Site watch: regular rechecks and alerts > Serpkin rechecks your verified sites on a schedule, alerts you when a deploy breaks something, and sums up the week every Monday. Canonical: https://serpkin.com/docs/site-watch Updated: 2026-11-03 | 5 min read ## In short - Site watch rechecks verified sites daily on Builder and Pro, including during the trial, with no credits. - Each check covers robots.txt, the sitemap, key pages, weekly Core Web Vitals and, with Search Console, indexing. - Alerts fire only for regressions on pages that were healthy, and at most one alert email goes out per site per day. - The weekly email arrives on Monday morning in your timezone and is skipped when nothing happened. A persistent assistant can read the same watch evidence and weekly summary with a monitor-only key. Ask it to discover your sites with `serpkin_get_workspace`, then review the chosen site's alerts. An MCP connection does not create a schedule in your agent; configure and confirm that routine separately. Implementation remains an explicit handoff. See [SEO with AI agents](https://serpkin.com/guides/seo-with-ai-agents). A site that's fine today can break with the next deploy: a stray `noindex`, a broken sitemap, a redirect loop. Site watch is Serpkin's regular recheck of your verified sites. It looks for regressions, sends an alert when something breaks, records early wins, and rolls it all into a weekly email. It uses no credits and runs on its own once your site is verified. ## How often it checks _Site watch cadence by plan_ | Plan | How often | Key pages per check | | --- | --- | --- | | Builder ($29 a month) | Daily | Up to 20 | | Pro ($79 a month) | Daily | Up to 25 | The trial includes the site watch of the plan you chose. Without a plan, sites are not watched. Only verified sites are watched: prove ownership with Search Console or the verification file first (see [Getting started](https://serpkin.com/docs/getting-started)). Checks run in a fixed time slot per site, so they spread out over the day or week, and they respect your robots.txt crawl delay, waiting at least one second between requests. ## What each check looks at - **robots.txt**, to catch new rules that block public pages. - **Your sitemap**, plus at most one child sitemap, including a few newly listed URLs. - **Key pages**: the homepage, pages from your missions, your top Search Console pages and your most-linked pages. - **Core Web Vitals**, at most once a week: the homepage and two key pages. - **Indexing**, with Search Console connected: a few URL inspections per check, for new sitemap URLs and pages changed by verified missions. Site watch is a light check, not a full scan. The deep crawl, with every page, the link graph and probes, runs when you or your agent start a scan. That keeps the watch fast and cheap enough to run daily. ## Alerts Alerts are conservative: a page only raises one if it was healthy in the previous check. The homepage has to be unreachable in two checks in a row, about 30 minutes apart, before Serpkin calls the site down. _What triggers an alert, and the fix Serpkin suggests_ | Alert | When | What to do | | --- | --- | --- | | Site unreachable | The homepage didn't respond in two checks in a row | Check your hosting and the latest deploy | | Page errors | A page that worked now returns an error | Restore it, or redirect it permanently to its replacement and update links | | Page hidden from search | A page gained noindex | Remove the noindex if the page should appear in search | | Canonical changed | A page's canonical no longer points to itself | Point it back to the page's own absolute URL, unless intended | | Sitemap broken | The sitemap stopped returning valid XML | Make sure it returns valid sitemap XML with HTTP 200 | | robots.txt blocking pages | A new Disallow rule blocks public pages | Remove the rule that blocks them | | Keyword left the top 10 | A tracked keyword dropped out of the top 10 after holding it | Open the related mission, if there is one | | Page got slower | Core Web Vitals regressed on a key page | Check what changed in the latest deploy | | Strong backlink lost | A strong site stopped linking to you | See the backlinks view for the page and the link | ### How alert emails are sent 1. **Detected** A check finds a regression and records an alert on the site. 2. **Batched** The first alert waits about 10 minutes, so related ones arrive together. 3. **Sent** At most one alert email per site per 24 hours. 4. **Resolved** When a later check finds the page healthy again, the alert closes on its own. _Alert emails are batched and capped so one bad deploy doesn't flood your inbox_ Alerts older than 48 hours that haven't been emailed are left to the weekly email instead. You can turn alert emails off in your account preferences, or with the unsubscribe link in any alert. ## Early wins Search results take time, so Site watch also records early progress before traffic shows up: a page indexed, first impressions in search, a first ranking in the top 100, a keyword entering the top 10 or reaching page one, clicks going up, and missions verified. Wins appear on the Results page and in the weekly email; they don't send alerts. ## The weekly email Every Monday from 08:00 in your timezone (UTC if Serpkin doesn't know it), you get one email per account with what changed on your verified sites: alerts, wins, verified missions, clicks when Search Console is connected, and your next mission. If nothing happened and there's no next mission, Serpkin skips the email rather than sending an empty one. > **Ask your agent instead** > > The same summary is available to your agent through `serpkin_weekly_summary`. Ask it "What changed on my site this week?" and it reads the same data the email uses. Numbers in the email only appear when they're measured, such as Search Console clicks or tracked keyword positions; nothing is estimated. For how missions are checked and measured, see [Verification and results](https://serpkin.com/docs/verification-and-results). What your competitors publish is tracked separately by [Competitor watch](https://serpkin.com/docs/competitor-watch), on its own weekly schedule. ## Questions ### Why isn't my site being watched? Site watch covers verified sites only. Prove ownership with Search Console or the verification file, then the first check runs on its own. ### Does site watch use credits? No. Site watch, its alerts and the weekly email are included on Builder, Pro and the trial, and never use credits. ## Related - [Verification and results](https://serpkin.com/docs/verification-and-results): Verification and results - [Competitor watch: what your competitors publish](https://serpkin.com/docs/competitor-watch): Competitor watch - [Getting started with Serpkin](https://serpkin.com/docs/getting-started): Getting started - [Troubleshooting: setup, scans, verification and weekly runs](https://serpkin.com/docs/troubleshooting): Troubleshooting --- # Competitor watch: what your competitors publish > Serpkin reads your competitors' public sitemaps every week, lists what they publish, and turns clear topic gaps into missions. Canonical: https://serpkin.com/docs/competitor-watch Updated: 2026-11-03 | 5 min read ## In short - Competitor watch reads public sitemaps weekly, with no credits and no search data, and respects robots.txt. - Builder and Pro check 5 competitors per site, including during the trial; you can add up to 5 per site by hand. - The first check is a baseline; later checks list pages that weren't in the sitemap before, minus tags, feeds and other noise. - Competitor publication alone does not qualify a mission; business fit, measured demand and a real content gap are required. Competitor watch reads your competitors' public sitemaps every week and lists the pages they publish. When a competitor covers a topic your site doesn't, it can become a mission for your agent. It uses no credits and no search data, only what each competitor already publishes for search engines, and it respects their robots.txt. ## Add a competitor 1. **Open Results, then the Competitors tab** Each site has its own list of competitors. 2. **Enter a domain, such as rival.com, and choose Watch** You can add up to 5 competitors per site by hand. Competitors found by keyword research appear in the list too; the ones you add come first. 3. **Wait for the first check** The first check is queued within the hour. After that, each site is checked once a week, at a fixed time between Monday and Wednesday (UTC). _Competitors checked per site, by plan_ | Plan | Competitors checked each week | | --- | --- | | Builder ($29 a month) | 5 | | Pro ($79 a month) | 5 | The trial checks as many competitors as the plan you chose. Without a plan, competitors are not checked, and your saved baselines are kept. Removing a competitor asks for confirmation, because it deletes its baseline. ## How it reads a competitor Serpkin finds the sitemap from the competitor's robots.txt, or at `/sitemap.xml`, and reads it the way a search engine does, within bounds: up to 6 sitemap files and 5,000 URLs per competitor. For up to 10 new pages each week it fetches the page once to read its title and heading. > **Polite by design** > > If a competitor's robots.txt can't be read (an error, a block or a rate limit), Serpkin fetches nothing that week. Pages and sitemaps that robots.txt disallows are never fetched, and the crawl delay is respected. If a domain redirects to a different site, the app tells you. ## What counts as new 1. **First check** Records every URL as the baseline. Nothing is called new yet. 2. **Each week** Compares the sitemap with last week's and finds URLs that weren't there. 3. **Filtered** Drops pages that aren't real content, and duplicates of the same page. 4. **Labeled** Reads the title and sorts the page: guide, comparison, tool, blog post and more. _The first check sets a baseline; later checks report pages that weren't there before_ On the first check you may still see a few pages marked **Recently updated**. Those come from sitemap dates within the last 30 days, and they mean the page changed recently, not that it's new. Sitemaps that stamp every URL with the same build time are ignored, because those dates say nothing about publishing. Shown - ✓Good:A page that wasn't in last week's sitemap - ✓Good:Guides, comparisons, free tools, blog posts, docs and landing pages - ✓Good:One entry per page, even when two URLs show the same page Ignored - ✕Problem:Pagination, tag, author and feed pages, and assets - ✕Problem:URLs with query strings and other-language copies - ✕Problem:Pages marked noindex, and pages that return an error _Only real, new content pages make it into the feed_ If more than 50 URLs, or 30% of a sitemap, change in one week, that usually means a redesign or migration rather than publishing. Serpkin treats that week as a new baseline instead of flooding your feed. ## From a competitor page to a mission A competitor publishing on a topic is a research lead, not proof that people search for it. Publication alone does not qualify a content mission. Topic recommendations need a complete audit, specific business fit, measured demand and a genuine gap in your existing pages. Research on a qualifying lead can support these formats: _Possible formats after relevance, demand and coverage checks_ | Competitor page | Mission | | --- | --- | | Comparison or alternatives page | A comparison page for your site | | Free tool or calculator | A free tool mission | | Guide or blog post | A new page on the topic | | Landing page, docs, changelog, integrations or customer story | No mission: these describe the competitor's own product | ### The rules - Only pages first seen in the last 45 days, and never "Recently updated" baseline items. - The inventory is checked for existing coverage and the topic is assessed against your business brief. Shared generic words are insufficient. Already-covered, tangential and uncertain topics are skipped. - At most 2 new missions per refresh, with a modest priority, so they never crowd out fixes or near-page-one wins. - Each mission links to the competitor page as its evidence. Write your own, more useful page; don't copy theirs. ## Where you see it The Competitors tab on Results shows the 20 most recent pages, grouped by competitor, each with its type, its path and when it was first seen, plus a link to any mission it created. The weekly email adds one line per competitor, such as "rival.com published 3 new pages", and your agent sees the same in `serpkin_weekly_summary`. For the missions themselves, see [Missions](https://serpkin.com/docs/missions). ## Questions ### Why does my feed say the first check set a baseline? The first check can't tell old pages from new ones, so it records every URL. New pages show up from the following week, apart from a few marked Recently updated from recent sitemap dates. ### Does Serpkin crawl my competitors' whole sites? No. It reads their sitemaps, within bounds, and fetches up to 10 new pages per competitor each week to read their titles. It never fetches pages that robots.txt disallows. ## Related - [Missions: what they are and how they're ranked](https://serpkin.com/docs/missions): Missions - [Site watch: regular rechecks and alerts](https://serpkin.com/docs/site-watch): Site watch - [Plans and limits](https://serpkin.com/docs/plans-and-limits): Plans and limits - [SEO MCP servers compared](https://serpkin.com/compare/seo-mcp-servers): SEO MCP servers --- # Content review: an AI second opinion on new pages > After your agent ships a page, an AI model checks it against what searchers ask and lists specific fixes. It's advisory and never changes verification. Canonical: https://serpkin.com/docs/content-review Updated: 2026-11-03 | 5 min read ## In short - A review runs as a follow-up job after a content mission passes verification, and on demand from the mission page. - Each review gives a verdict, checks the opening, lists missed questions, and suggests 3 to 6 specific fixes. - Reviews are advisory: they never change a mission's status or a verification outcome. - Builder includes 60 reviews a month and Pro 250, the same during the trial, with no credits used. Your coding agent wrote the page, so it isn't the best judge of whether the page is good. Content review is a second opinion: after a content mission passes verification, an AI model reads the published page, compares it with the target search and the mission's content brief, and lists specific fixes. It's advisory. It never changes whether a mission passed, and it doesn't predict rankings. ## When a review runs 1. **Verified** A content mission passes verification on preview, production or evidence. 2. **Queued** Serpkin queues the review as a follow-up job, usually done in about a minute. 3. **Reviewed** The model reads the page against the target search and the brief. 4. **Shown** The review appears on the mission, with fixes you can copy for your agent. _Reviews run after verification, as a separate step, so verification never waits on the model_ Reviews only run on missions where the page is content worth reviewing: - New pages, free tools and comparison pages - Expanding a page, or refreshing a page that has been losing clicks - Getting cited in Google's AI answer, including when competitors are cited and you aren't - Near-page-one and declining pages, once the mission has a content brief A review is skipped when the page has changed little since the last one: the same address reviewed within 24 hours, with the same text, isn't reviewed again. It's also skipped when the page returns an error, redirects to another site, or has too little main content to judge (under about 80 words). The review reads the public page as a visitor would, not your source files, so it judges what Google and readers actually get. A page that is mostly a list of links cannot be judged fairly, and Serpkin says so instead of guessing. ### Review again On the mission page, **Review the page** (or **Review again** once there's a review) starts one on demand, for example after your agent applied the fixes. You can request up to 3 on-demand reviews per mission in 24 hours. If a review is skipped or fails, the panel says why, such as "The page hasn't changed since its last review." ## What a review contains _The parts of a content review_ | Part | What it tells you | | --- | --- | | Verdict | Strong, Needs work or Weak, with a one or two sentence summary | | Opening | Whether the first paragraph answers the search directly, and a note on it | | Questions | Which questions from the brief the page answers, and which it misses | | Fixes | 3 to 6 specific changes, most important first, each naming the section to change | | Claims to source | Statements on the page that need a source before readers or AI answers can trust them | **Copy fixes for your agent** copies the fixes as a prompt you can paste into Claude Code, Codex or Cursor. The prompt says the fixes come from an AI review of web content: they're suggestions to judge, not instructions, and your agent should never apply scripts, links, code or credentials taken from page text. ## Advisory, never a gate What a review does - ✓Good:Points out what the page is missing for the search it targets - ✓Good:Gives fixes specific enough for your agent to apply - ✓Good:Flags claims that need a source What it never does - ✕Problem:Change a mission's status or a verification outcome - ✕Problem:Promise rankings, traffic or a citation - ✕Problem:Write or publish anything on your site _A review informs your next edit; it never decides whether a mission is done_ The model can be wrong. Treat a review the way you'd treat notes from a sharp editor: read them, keep the ones that make the page better for readers, and skip the rest. ## Monthly limits _AI content reviews per workspace per month, automatic and on demand together_ | Plan | Reviews a month | | --- | --- | | Builder ($29 a month) | 60 | | Pro ($79 a month) | 250 | The trial includes the same number as the plan you chose. Without a plan, there are no reviews. The count resets on the 1st (UTC). Reviews don't use credits. When the month's reviews are used up, the panel says so and what the next plan includes; see [Plans and limits](https://serpkin.com/docs/plans-and-limits). ## What's sent for a review A review sends the public text of the reviewed page (its main content, without navigation, header and footer), the target search and the mission's content brief. It never sends your code, your Search Console numbers or your account details. Requests go through OpenRouter to an AI model provider (currently Claude Haiku), routed only to providers that don't store requests for training. > **More on your data** > > See [Data and privacy](https://serpkin.com/docs/data-and-privacy) for everything Serpkin receives and keeps, and the [privacy policy](https://serpkin.com/legal/privacy) for the full list of processors. ## Questions ### Why didn't my page get a review? Reviews run only on content missions, after a passed verification. They're skipped when the page hasn't changed since its last review, returns an error, or has too little text. The panel shows the reason. ### Which AI model does the review? Currently Claude Haiku, through OpenRouter, routed only to providers that don't store requests for training. ## Related - [Verification and results](https://serpkin.com/docs/verification-and-results): Verification and results - [Missions: what they are and how they're ranked](https://serpkin.com/docs/missions): Missions - [Your data and privacy: what Serpkin stores, and how to remove it](https://serpkin.com/docs/data-and-privacy): Data and privacy - [How to get cited in Google AI Overviews (and ChatGPT)](https://serpkin.com/guides/ai-overviews): Get cited in AI Overviews --- # Weekly pull requests: one SEO mission a week, opened for review > For teams who want SEO work to happen every week without starting it. One workflow, one mission, one draft pull request, and you still review and deploy. Canonical: https://serpkin.com/docs/weekly-pull-requests Updated: 2026-10-29 | 7 min read ## In short - The workflow runs every Monday at 08:00 UTC, gets your top mission, and opens one draft pull request labeled serpkin. - It stops while a Serpkin pull request is still open, so missions never pile up. - Claude Code gets file tools only, and a separate job rejects workflow, dependency, env and git changes. - Weekly runs use no Serpkin credits. GitHub Actions and Anthropic usage are billed by those providers. Weekly pull requests are Serpkin's hands-off mode. Every Monday, a GitHub Actions workflow asks Serpkin for your top mission, has Claude Code implement it on a new branch, and opens one draft pull request for you to review. Nothing is merged or deployed without you. This page explains what each run does, how to turn it on, what the pull request contains and when a run decides to stop. ## What happens each week 1. **Check the queue** The run stops if a pull request labeled serpkin is still open. Otherwise it gets the next mission and marks it in progress. 2. **Implement** Claude Code reads the mission file and edits files in a checkout. It gets file tools only, no shell and no secrets. 3. **Check the change** A separate job rejects changes to workflows, dependencies, env files or git internals, and scans for secrets. 4. **Open a draft** The rest is committed to a new branch and opened as a draft pull request with the serpkin label. _One scheduled run, from the mission queue to a pull request you can review_ The default schedule is Mondays at 08:00 UTC. A run typically takes a few minutes. Your own CI and preview deployment then test the pull request, and the mission waits in Serpkin as implemented until you verify it after deploying. You can also start a run by hand from the Actions tab with `workflow_dispatch`, which is useful after changing secrets or checking that the setup works. ## Turn it on 1. **Add the workflow files** In your repository, run `npx serpkin weekly`. It writes `.github/workflows/serpkin-weekly.yml` and, if you don't have one yet, the preview SEO check at `.github/workflows/serpkin.yml`. Existing files are kept. `--force` replaces the weekly workflow, and in a monorepo you run the command from the app folder so the files land at the repository root. 2. **Add two secrets and one variable** The workflow needs a Serpkin agent key as `SERPKIN_API_KEY`, an Anthropic key as `ANTHROPIC_API_KEY` (or a Claude subscription token as `CLAUDE_CODE_OAUTH_TOKEN`), and your site id as the repository variable `SERPKIN_SITE_ID`. The command prints the exact `gh secret set` and `gh variable set` lines. `gh` asks for each value, so a key never lands in your shell history. 3. **Commit, push, and run it once** Commit the workflow files and push. Then run the workflow by hand once and read the log. When it succeeds, the pull request appears under Pull requests with the label `serpkin`, and the mission in Serpkin shows as implemented with the pull request URL attached. The full setup, including the optional `SERPKIN_PR_TOKEN` for letting your CI run on the pull request, is in [Serpkin in GitHub Actions](https://serpkin.com/integrations/github-actions). That page also has the complete workflow file if you prefer to copy it by hand. ## What the pull request contains - **A branch per run:** named `serpkin/-`. The workflow never pushes to your default branch. - **A title from the mission:** `SEO: `, trimmed to fit GitHub. - **A description in three parts:** what changed and why, the files changed, and each acceptance check with how the agent met it. - **The label:** `serpkin`, which is also how the next run knows a pull request is still waiting for you. - **A note at the bottom:** a reminder that your CI and preview deployment test the change, and that you merge and deploy it yourself. The pull request is a draft on purpose. Mark it ready when you have read the diff. If the mission can't be done safely in code, for example because it needs a DNS change or a new dependency, Claude Code changes no files and writes the reason to the run summary. The workflow then dismisses the mission in Serpkin with a note, so next week's run moves on instead of retrying the same blocked task. You can restore the mission in Serpkin and do it yourself. ## How it stays safe Mission text can quote page titles, search queries and competitor copy from the web, so a page could try to steer the agent. The workflow is built so that even a misled agent cannot do damage. It runs in three separate jobs with different permissions: _The three jobs and what each one can do_ | Job | Can do | Cannot do | | --- | --- | --- | | prepare | Call Serpkin with your agent key and read the mission | Run repository code | | implement | Read and edit files in the checkout and the mission folder | Run shell commands, use the network, commit, push or see the Serpkin key | | publish | Apply the patch, push a new branch and open a draft pull request | Run repository code or change protected files | The publish job rejects changes to `.github/`, git internals, `package.json`, lockfiles, env files, deploy configuration such as `vercel.json`, symlinks and submodules. It also refuses a patch or description that looks like it contains a key or token, before anything is pushed. The patch is built in a fresh checkout with git hooks and user config disabled, so the agent cannot plant settings that the workflow would then trust. Actions are pinned to commit SHAs, every job has a timeout, and a concurrency group stops two runs from overlapping. > **Use a dedicated agent key** > > Create the Serpkin key for this repository and revoke it if the workflow is removed. Keep production secrets out of preview environments, because your host builds a preview for the pull request like any other branch. For defense in depth, protect your default branch so every change needs a reviewed pull request. ## Review, merge, then verify 1. **Read the description and the diff** Start with the three sections in the description, then check the diff against the mission steps. The change should be focused on one mission. If it isn't, close the pull request and dismiss the mission with a reason instead of editing it into shape. 2. **Let CI and the preview check finish** Your normal CI runs on the branch. If the preview SEO check is installed, it compares the preview with production and fails on regressions such as a new `noindex`, a removed canonical or a broken sitemap. A red check is information, not a blocker you should ignore. 3. **Merge and deploy** Mark the draft ready, merge it, and deploy the way you normally do. Serpkin does not deploy anything for you and does not need deploy access. 4. **Verify the mission in production** Ask your agent to verify the mission, or run `npx serpkin check ` first. A passed verification starts the measurement window, with results at 14 and 28 days. See [Verification and results](https://serpkin.com/docs/verification-and-results). Weekly runs use no Serpkin credits. Missions, submissions and verification are included in your plan. GitHub Actions minutes and Anthropic usage are billed by those providers, not by Serpkin. ## When a run skips or stops _Why a weekly run may do nothing, and what to do_ | What you see | Why | What to do | | --- | --- | --- | | A notice that a Serpkin pull request is still open | The previous week's pull request is waiting for review | Review and merge it, or close it and dismiss the mission | | A notice that there is no open mission | Everything is done or still being measured | Nothing to do. New missions appear after the next scan or data refresh | | A warning that no change was made | The mission needs work outside the code | Read the run summary, restore the mission in Serpkin, and do it yourself | | An error about files the workflow doesn't allow | The mission needed a workflow, dependency or config change | Nothing was pushed. Restore the mission and make that change yourself | | A 401 from Serpkin | The agent key is missing, revoked or for another workspace | Create a new agent key and set the secret again | | CI did not run on the pull request | It was opened with the default GitHub token | Add the optional SERPKIN_PR_TOKEN secret | GitHub can delay scheduled runs when Actions is busy. In public repositories it also turns scheduled workflows off after 60 days without repository activity, so run the workflow by hand to wake it up. If your team works in several time zones, change the cron line to a time that suits the person who reviews the pull request. ## Change the schedule and scope _Common changes_ | Change | Where | | --- | --- | | Another day or time | The `cron` line, in UTC. `0 8 * * 1,4` runs Mondays and Thursdays. | | Claude Pro or Max instead of an API key | Comment out `anthropic_api_key` and uncomment `claude_code_oauth_token`. | | Another Serpkin server | `npx serpkin weekly --server https://seo.example.com`, or edit `SERPKIN_SERVER`. | | A pull request against another base branch | Start the workflow by hand from that branch. The base is the branch the run started on. | | No pull requests at all | Remove the workflow file. Missions still work through your agent on demand; you lose the automatic weekly start. | The schedule is a starting point, not a rule. Teams that review quickly often run it twice a week; teams that deploy rarely leave it weekly and let a pull request stay open until they have time. The one-open-pull-request guardrail keeps either rhythm from piling up work. > **Close the loop** > > A merged pull request is not a finished mission. Deploy it, then verify. Serpkin measures the result at 14 and 28 days, and the next weekly run only starts after the current pull request is out of the way. ## Questions ### Does Serpkin merge or deploy the pull request? No. The workflow opens a draft pull request. You review the diff, your CI and preview deployment test it, and you merge and deploy it yourself. ### What if I don't review last week's pull request? Next week's run skips and writes a notice. Nothing piles up. Review or close the open pull request and the following run picks up the next mission. ### Can I run it more than once a week? Yes. Change the cron line to any schedule, or start the workflow by hand. The one-open-pull-request guardrail still applies. ### Does the workflow need my source code? It checks out your repository inside GitHub Actions, which is your own infrastructure. Serpkin receives the mission and the pull request URL, not your source code. ## Related - [SEO checks in GitHub Actions](https://serpkin.com/integrations/github-actions): GitHub Actions - [Missions: what they are and how they're ranked](https://serpkin.com/docs/missions): Missions - [Verification and results](https://serpkin.com/docs/verification-and-results): Verification and results - [CLI reference](https://serpkin.com/docs/cli): CLI --- # MCP tools and prompts reference > All tools and prompts your coding agent can use, generated from the server's own contract, so this list always matches what the server offers. Canonical: https://serpkin.com/docs/mcp-tools Updated: 2026-10-29 | 6 min read ## In short - Serpkin's MCP server has 30 tools and 7 prompts; this list is generated from its contract. - The loop: serpkin_next_mission, implement, serpkin_submit_result, then serpkin_verify_mission on the preview and in production. - Reading is free. Research tools that cost credits say so, and the agent asks you before spending them. - At a plan limit, the error carries an upgrade note that the agent mentions once, with the link. Tools-only clients can start with `serpkin_get_workspace`, without a repository or MCP resource support. The authenticated connection supplies `project_id` when omitted; an explicit different workspace is rejected. The server advertises tools permitted by the key's role and enforces access on calls. Refresh variants can require research access even when their read variants are available. Use `serpkin_get_handoff` for a versioned brief, not external-agent dispatch. See [agent access and connections](https://serpkin.com/docs/ai-agents). Serpkin is an MCP server with 30 tools and 7 prompts. Your coding agent calls them; you rarely need to name them yourself. This page lists every tool from the server's own contract, grouped by job, with what it does, its main inputs and what it costs. Inputs marked with * are required. Every call also takes a `project_id`. ## How the agent uses them The server tells every agent the same loop when it connects: 1. **serpkin_next_mission** Get the one mission worth doing now, with files and steps. 2. **Implement** Edit the listed files, adapt the snippets, run your tests. 3. **serpkin_submit_result** Record the pull request, commit and preview URL. 4. **serpkin_verify_mission** Check the preview, then production after a person deploys. _The mission loop. Merging and deploying stay with a person; verification after a deploy is what closes a mission._ Read tools are free. Research tools that cost credits say so, and the server tells the agent to state the cost and ask you first. If a mission isn't relevant or is already done, the agent dismisses it with `serpkin_update_mission` and a reason. ## Find and ship the work Pick the next mission, read it, record the change and verify it. _Find and ship the work: 10 tools_ | Tool | What it does | Main inputs | Credits | | --- | --- | --- | --- | | `serpkin_next_mission` | The single most useful open mission, with why now, the files to change, a step-by-step plan and the checks that prove it's done. | site_id* | Free | | `serpkin_scan_site` | Queue a technical scan that creates foundation missions. | site_id*, idempotency_key* | Free | | `serpkin_get_missions` | The ranked list of missions for a site, filterable by status and category. | site_id*, status, category, limit, cursor | Free | | `serpkin_get_mission` | A full mission by id: rationale, targets, source files, recipe, implementation plan and acceptance criteria. | mission_id* | Free | | `serpkin_create_mission` | Turn a saved opportunity into a mission, without duplicates. | site_id*, opportunity_id*, category*, idempotency_key* | Free | | `serpkin_get_site_context` | The site's business, market, framework, ownership and health from the latest full scan. | site_id* | Free | | `serpkin_submit_result` | Record what was shipped: pull request, commit, preview URL and test summary. | mission_id*, artifacts*, notes, idempotency_key* | Free | | `serpkin_verify_mission` | Check a submitted mission on the preview, in production, or against evidence for content work. | mission_id*, environment*, preview_url, idempotency_key* | Free | | `serpkin_update_mission` | Start, dismiss or restore a mission. Dismissing takes a reason and an optional note. | mission_id*, action*, reason, note, idempotency_key* | Free | | `serpkin_get_handoff` | Get a versioned implementation brief and tracking instructions; does not dispatch another agent. | mission_id* | Free | ## Measure and watch Search performance, rankings, results, backlinks, AI visibility and site health. Reading is free. _Measure and watch: 10 tools_ | Tool | What it does | Main inputs | Credits | | --- | --- | --- | --- | | `serpkin_get_performance` | Daily clicks, impressions, CTR and position, with mission markers and top queries. | site_id*, period, country, language, limit, cursor, … | Free | | `serpkin_track_keywords` | Get, add, remove or replace the site's tracked keywords. | site_id*, action*, keyword_ids, country, language, idempotency_key, … | Free | | `serpkin_compare_performance` | The last 28 days of Search Console data against the 28 days before. | site_id*, period*, comparison_period*, country*, language* | Free | | `serpkin_get_mission_history` | A mission's events in order: lifecycle, implementation, verification and results. | site_id*, mission_id, limit, cursor | Free | | `serpkin_get_results` | Measured results of shipped missions at the baseline, 14 and 28 days. | site_id*, mission_id, limit, cursor | Free | | `serpkin_get_ai_visibility` | Whether Google shows an AI Overview for your important queries and whether it cites you. | site_id*, refresh, queries, idempotency_key | Free to read; 1 per query to check now | | `serpkin_get_rankings` | Tracked keyword positions, 7-day changes, ranking URLs and suggested keywords. | site_id* | Free | | `serpkin_get_backlinks` | Referring domains, new and lost links, links to broken pages and the link gap. | site_id*, refresh, idempotency_key | Free to read; 5 per refresh | | `serpkin_site_watch` | Is my site OK? The scheduled check's open alerts and recent wins. | site_id* | Free | | `serpkin_weekly_summary` | The Monday "Your SEO week" summary as data, per site. | site_id | Free | ## Research Keywords, results pages, competitors and content briefs. Some of these spend credits. _Research: 7 tools_ | Tool | What it does | Main inputs | Credits | | --- | --- | --- | --- | | `serpkin_research_keywords` | Keyword ideas with volume, difficulty and intent for a seed phrase. | site_id, query*, country*, language*, limit, cursor, … | 2 per seed | | `serpkin_cluster_keywords` | Group saved keywords into topics, with page matches and overlap warnings. | site_id, keyword_ids*, country*, language*, idempotency_key* | Free | | `serpkin_analyze_serp` | The current top results for up to 3 keywords. | site_id, keywords*, country*, language*, limit, cursor, … | 1 per keyword | | `serpkin_research_competitors` | The site's organic search competitors in a market. | site_id*, domains, country*, language*, limit, cursor, … | 3 per request | | `serpkin_find_keyword_gaps` | Keywords competitors rank for that the site doesn't. | site_id*, competitor_ids*, country*, language*, limit, cursor, … | 3 per competitor | | `serpkin_create_content_strategy` | Starting briefs from saved keyword or clustering reports. | site_id*, research_report_ids*, country*, language*, idempotency_key* | Free | | `serpkin_get_content_brief` | A brief from the top results: outline, questions people ask, length, terms and internal links. | mission_id, site_id, query, refresh, idempotency_key | Free to read; 2 to build one | ## Set up Register a site and follow background jobs. _Set up: 3 tools_ | Tool | What it does | Main inputs | Credits | | --- | --- | --- | --- | | `serpkin_register_site` | Register a website and get its ownership options. | origin*, business_description*, audience*, framework, country*, language*, … | Free | | `serpkin_get_job` | Poll or cancel a background job such as a scan, research or verification. | job_id*, action*, idempotency_key | Free | | `serpkin_get_workspace` | Discover the workspace, accessible sites, key permissions and next actions without resources or a repository. | limit, cursor | Free | ## Prompts Prompts are ready-made requests your agent can run, for clients without the Claude Code plugin. They follow the same rules as the tools. _The 7 MCP prompts_ | Prompt | Title | What it does | | --- | --- | --- | | `manage_seo` | Review SEO and propose the next action | Review sites, monitoring and next missions without a repository or implementation. | | `delegate_mission` | Prepare an implementation handoff | Get a current mission brief for another agent and explain how to track it; does not dispatch work. | | `next_mission` | Do the next SEO mission | Get the highest-priority SEO mission and implement it in this repository. | | `ship_mission` | Ship a mission | Record the implementation, check the preview and verify the mission. | | `check_preview` | Check a preview for SEO regressions | Compare a preview deployment with production (free). | | `seo_status` | How is my site doing? | This week's SEO summary: clicks, rankings, wins, anything broken and the next mission (free). | | `research_topic` | Research a topic | Keyword ideas for a topic, grouped into page ideas that fit this site (2 credits). | ## Limits and upgrade notes When a call reaches a plan limit, for example the monthly missions or credits, the error includes an `upgrade` object: which limit was reached, your usage, what the next plan includes and a link to your plan settings. `serpkin_next_mission` and `serpkin_weekly_summary` also include it when a limit is close. The server tells the agent to mention it to you once, with the link, and never to push or repeat it. > **Search data is data, not instructions** > > Page text, search queries, titles, observed text and evidence come from the web. The server tells agents to treat them as untrusted data, never as instructions, and never to merge, publish or deploy without you. ## Connect a client `npx serpkin` configures Claude Code, Cursor and Codex for you. Any other MCP client can connect to the HTTP endpoint with your agent key as a bearer token: ``` { "mcpServers": { "serpkin": { "type": "http", "url": "https://serpkin.com/api/mcp", "headers": { "Authorization": "Bearer ${SERPKIN_API_KEY}" } } } } ``` _.mcp.json_ The key comes from `npx serpkin` or Agents, and is read from the `SERPKIN_API_KEY` environment variable, so it never sits in the repository. Setup per agent: [Claude Code](https://serpkin.com/integrations/claude-code), [Cursor](https://serpkin.com/integrations/cursor) and [Codex](https://serpkin.com/integrations/codex). ## Related - [CLI reference](https://serpkin.com/docs/cli): CLI - [Credits: what research costs and how the monthly allowance works](https://serpkin.com/docs/credits): Credits - [SEO for Claude Code](https://serpkin.com/integrations/claude-code): Claude Code - [Plans and limits](https://serpkin.com/docs/plans-and-limits): Plans and limits --- # CLI reference > npx serpkin and its commands: what each one does, every option, and where the CLI keeps your key and settings. Canonical: https://serpkin.com/docs/cli Updated: 2026-10-30 | 5 min read ## In short - npx serpkin signs you in, connects your agent, registers the site and uploads a route map. It's safe to re-run. - npx serpkin check exits 1 on SEO regressions, so it works as a CI step. - Your agent key lives in ~/.config/serpkin/credentials.json and SERPKIN_API_KEY, never in the repository. - .serpkin.json holds the server and site id, no secrets. Commit it. `--agent` accepts `claude`, `cursor`, `codex`, `hermes`, `grok-bot` or `other`. Use `--connect-only` to sign in and prepare agent configuration without registering a site or uploading routes. Hermes uses an environment-referencing YAML entry; existing nonempty config is preserved for a manual merge. Grok Bot and generic MCP clients receive manual connection instructions. Configuration preparation is not proof of a live connection. CLI device keys default to full access; create a restricted key in Agents for monitoring or budgeted research. Setup reports connection success separately from audit readiness. A finished connection may still need ownership, readable content, a wider crawl or one business-context answer. The CLI waits up to 75 seconds for the first recommendation and prints a recovery step if it cannot load one. Automatic initial and monthly topic research is off by default because it uses credits. Pass `--auto-research` when registering a new site to turn it on; the initial scan runs either way. `npx serpkin next --refresh` skips the six-hour cache and asks the server for the latest next mission. Review country and language in the setup receipt. A public site or preview is required. The Serpkin CLI connects your coding agent, registers your site and checks preview deploys. It needs Node 22 or newer and runs with `npx`, so there's nothing to install. Every command below is safe to re-run. ## Commands _Serpkin CLI commands_ | Command | What it does | | --- | --- | | `npx serpkin` | Setup: sign in, connect your agent, register the site and upload the route map. Same as serpkin init. | | `npx serpkin check ` | Compare a preview deploy with production. Exit code 1 on regressions, 2 on errors. | | `npx serpkin verify` | Check site ownership through the verification file or DNS record. | | `npx serpkin status` | Site, ownership, data level, next mission and credits. | | `npx serpkin next` | The next mission in one line. Fast and cached; --oneline stays silent when offline. | | `npx serpkin routes` | Print the route map; --upload sends it. | | `npx serpkin weekly` | Add GitHub Actions: a weekly mission pull request and the preview SEO check. | ### Setup ``` $ npx serpkin Open https://serpkin.com/cli and confirm the code BCDF-GHJK ✓ Signed in. Key saved to ~/.config/serpkin/credentials.json (outside this repo) ✓ Site registered: https://acme.dev (.serpkin.json saved; it holds no secrets) ``` _Terminal: npx serpkin (illustrative)_ Sign-in opens `https://serpkin.com/cli` with a short code. Confirm it matches your terminal and approve: that creates an agent key named after your machine, which you can revoke in Agents. The CLI then detects your framework, connects Claude Code, Cursor or Codex, registers the site and uploads a route map (URL path to source file). Registration queues the initial audit on the server. The CLI waits up to 75 seconds and shows a mission when one is ready. Pass `--no-wait` to finish setup without waiting; the audit continues. ### Check a preview ``` $ npx serpkin check https://acme-git-seo.vercel.app ✓ No SEO regressions across 6 pages. ``` _Terminal: npx serpkin check (illustrative)_ It compares up to 25 paths on the preview and on production (by default the homepage plus up to 10 known pages) and fails on HTTP errors, a `noindex` added in the page's robots meta tag, a removed title, meta description or H1, a broken canonical, or a failing `robots.txt` or sitemap. Problems that already exist in production are warnings, not regressions. Header-level `noindex` on a preview is a warning too, because hosts such as Vercel add it to every preview. > **Protected previews** > > If your previews use deployment protection, Serpkin gets HTTP 401 and reports the preview as unreachable. Allow its requests, or check a public preview. Preview hosts must be your own domain or subdomains, or `*.vercel.app`, `*.netlify.app` or `*.pages.dev`. ### Weekly pull requests ``` npx serpkin weekly ``` _Terminal_ Writes `.github/workflows/serpkin-weekly.yml`, and the preview check `.github/workflows/serpkin.yml` if it's missing, then prints the `gh secret set` commands to run. Existing files are kept; `--force` replaces the weekly workflow. See [Weekly pull requests](https://serpkin.com/docs/weekly-pull-requests). ## Options _CLI options_ | Option | What it does | | --- | --- | | `--url ` | Production URL, or a preview URL if the site isn't live yet. | | `--server ` | Serpkin server. Default: $SERPKIN_SERVER, then .serpkin.json, then https://serpkin.com. | | `--agent ` | Which agents to connect: claude, cursor, codex (comma-separated). | | `--plugin` | Claude Code: install the Serpkin plugin without asking. | | `--app ` | App directory in a monorepo, for example apps/web. | | `--ownership ` | file, search-console or skip. | | `--description, --audience, --country, --language` | Site details for registration. | | `--login` | Sign in again even if a key is stored. | | `--paths ` | check: the paths to compare (max 25). | | `--site ` | Site id. Default: .serpkin.json or $SERPKIN_SITE_ID. | | `--upload` | routes: upload the route map. | | `--force` | weekly: replace an existing weekly workflow. | | `--json` | Machine-readable output. | | `--yes, -y` | Accept defaults and never prompt. | | `--no-browser` | Don't open a browser. | | `--no-wait` | init: skip waiting for the audit and the first-mission reveal. Registration still queues the audit. | | `--no-scan` | Compatibility alias for --no-wait; does not cancel the server-queued audit. | Without a terminal (in CI) or with `--yes`, the CLI never prompts. When it needs something it can't default, it stops and names the flag to pass. ## Files and environment _Where the CLI keeps things_ | Item | Where | Notes | | --- | --- | --- | | Agent key | `~/.config/serpkin/credentials.json` | Mode 600, never in the repository. | | .serpkin.json | Repository root | Server, site id and origin. No secrets; commit it. | | SERPKIN_API_KEY | Environment | The key your agent's MCP config reads. | | SERPKIN_SERVER | Environment | Overrides the server. The key is only ever sent to this server, or to https://serpkin.com when unset. | | SERPKIN_SITE_ID | Environment | Site id for commands such as check, when there's no .serpkin.json. | ``` { "server": "https://serpkin.com", "site_id": "", "origin": "https://acme.dev" } ``` _.serpkin.json_ > **Which server gets your key** > > `.serpkin.json` is repository content, so it can't send your key somewhere new. A server named only there is used when it's `https://serpkin.com` or a server you already signed in to. Otherwise the CLI asks, and without a terminal it stops until you pass `--server` or set `SERPKIN_SERVER`. ## What leaves your machine Serpkin receives your site URL, the answers you give during setup, the route map (URL paths and the file names that serve them, up to 2,000 routes) and your computer's hostname at sign-in, used to name the agent key. It never receives your source code, environment files or repository contents: to build the route map, the CLI reads `package.json` and the file names in your routes folder, not their contents. More in [Data and privacy](https://serpkin.com/docs/data-and-privacy). ## Related - [MCP tools and prompts reference](https://serpkin.com/docs/mcp-tools): MCP tools - [Weekly pull requests: one SEO mission a week, opened for review](https://serpkin.com/docs/weekly-pull-requests): Weekly pull requests - [SEO checks in GitHub Actions](https://serpkin.com/integrations/github-actions): GitHub Actions - [Your data and privacy: what Serpkin stores, and how to remove it](https://serpkin.com/docs/data-and-privacy): Data and privacy --- # Plans and limits > Prices, the free trial and every plan limit, read from the code that enforces them, plus what happens when you reach one. Canonical: https://serpkin.com/docs/plans-and-limits Updated: 2026-11-03 | 5 min read ## In short - Builder is $29 a month and Pro $79 a month; yearly billing gives 2 months free. - Both start with a 7-day free trial. A card is required, and you are charged on day 8 unless you cancel before then. - The trial includes the full plan, except research credits are capped at 150. Builder then includes 3 sites, 30 missions and 500 credits a month. - Without a plan you get one site with a preview audit of up to 6 pages. Missions, scans and monitoring need a trial or a subscription. - At a limit, nothing is deleted: that action waits, and Serpkin says what the next plan includes. > **Paid checkout is not open yet** > > This page describes Serpkin once checkout opens: two plans, each with a 7-day free trial. Until then, new workspaces start on the current Free plan, and your plan settings show what it includes. Serpkin has two plans, Builder and Pro. Each starts with a 7-day free trial. Without a plan you can add one site and see its preview audit, but missions, scans and monitoring need a trial or a subscription. Every paid limit below is read from the same code that enforces it. Usage resets on the 1st of each month (UTC). ## Prices _Plan prices in US dollars_ | | Builder | Pro | | --- | --- | --- | | Free trial | 7 days | 7 days | | Monthly | $29 | $79 | | Yearly | $290 (2 months free) | $790 (2 months free) | Allowances are the same on monthly and yearly billing, and they reset monthly on both. Payment, the trial and plan changes are covered in [Billing](https://serpkin.com/docs/billing). ## The 7-day free trial Choose Builder or Pro, monthly or yearly, and enter a card. You get all of that plan's features for 7 days, with one exception: research credits are capped at 150 during the trial. You are charged on day 8 unless you cancel before then. When the trial converts, the full allowance applies right away. Cancel in Account, under Billing, or in the Creem customer portal. If you cancel during the trial, you are not charged, and you keep access until the trial ends. Each workspace gets one trial. A later subscription starts as a paid plan right away. ## Without a plan A workspace has no plan after sign-up until you start a trial, and again after a trial or subscription ends. Without a plan you can: - add one site and get a preview audit of up to 6 pages - see the findings from that audit - export or delete your data - start a trial, or a subscription if you already used your trial Missions, full scans, research credits, rank tracking, site watch, digests and alerts need a plan. So do automatic research, briefs, backlink snapshots, AI visibility checks and IndexNow pings. A blocked action returns the error code `TRIAL_REQUIRED` with a checkout link, so your agent can tell you what to do next. Everything you saved stays readable. The first audit is queued when you add a site and uses the same monthly scan allowance. Preview scope is 6 pages until ownership is verified. If scans are used up, the site is still saved and its audit waits until scans are available. Auditing public pages and assessing business fit do not spend search credits; optional initial and monthly keyword discovery can use plan credits within the stated reserve and safety caps. Advisory content reviews have their own allowance. Mission allowances are a maximum, never a target to fill. ## When your site is larger than a scan Builder checks up to 150 pages per full scan, and Pro 500. A partial audit keeps technical findings from checked pages. New content recommendations wait until discovered content coverage is complete, so an identical scan on the same plan cannot solve a page-cap limit. Compare the discovered count with plan capacity before changing plan; a larger site can exceed any plan. JavaScript rendering has a separate allowance per scan. Making main content readable in server HTML is another way to resolve unreadable pages. A mission allowance counts new missions created in the month, including automatically generated missions. Copying, starting or completing a mission does not consume another. The allowance is a ceiling, not a promise that every site needs that much work. ## What each plan includes _Limits per plan, read from the code that enforces them_ | | Builder | Pro | | --- | --- | --- | | Sites | 3 | 15 | | New missions a month | 30 | 150 | | Research credits a month | 500 (150 during the trial) | 1,500 (150 during the trial) | | Full scans a month | 12 | 30 | | Pages per full scan | 150 | 500 | | Pages rendered with JavaScript per scan | 10 | 25 | | Tracked keywords | 100, checked daily | 300, checked daily | | Site watch | Daily, up to 20 pages | Daily, up to 25 pages | | AI content reviews a month | 60 | 250 | | Competitors watched per site | 5 | 5 | Until a site's ownership is verified, its scans are a short preview of up to 6 pages on every plan. You can add up to 5 competitors per site on any plan; the competitor watch checks as many as your plan includes. What credits pay for is listed in [Credits](https://serpkin.com/docs/credits). ## Choosing a plan _Which plan fits, by how you work_ | Plan | Fits when | Why | | --- | --- | --- | | Builder | You run a few sites and ship SEO fixes every week | 3 sites, 30 new missions a month, daily site watch and rank checks, and 150 pages per full scan. | | Pro | You run many sites or client projects | 15 sites, 150 new missions a month, 1,500 credits and 500 pages per full scan. | Scans read your pages the way a crawler does. Larger plans read more pages per scan, and some render pages with JavaScript when the server HTML looks empty, which matters for single-page apps. Tracked keywords and the site watch are checked daily on both plans. ## When you reach a limit Nothing breaks and nothing is deleted. The action that would go over the limit is refused with a plain message that says which limit you reached and what the next plan includes. Everything you already have keeps working. Keeps working - ✓Good:Open missions, results and history - ✓Good:Verification of work you already shipped - ✓Good:Site watch and the weekly email - ✓Good:Reading performance, rankings and backlinks Waits for next month or an upgrade - ·New missions beyond the monthly limit - ·Research that needs more credits than remain - ·Another site beyond your plan's sites - ·Full scans beyond the monthly limit _Reaching a limit stops new work of that kind until the month resets or you upgrade. Existing data and missions stay._ In the app, a short note appears when you get close to a limit or reach it, with a link to your plan settings. Your coding agent gets the same note in the tool result and mentions it to you once. ## After a downgrade, pause or cancel If you move from Pro to Builder, the oldest sites up to the new limit stay fully active. The rest become watch-only: they keep all their history and are still checked by the site watch, but new scans, research and verification for them need the larger plan again. When a trial ends without converting, or a subscription is cancelled, paused or expires, the workspace has no plan. Your data is kept and stays readable, but scans, site watch, rank checks and alerts stop. Choose Start subscription in Account to pick up where you left off. A second trial is not available. > **Not sure which plan fits?** > > Start a trial of Builder. Your plan settings show this month's usage for each limit, so you can see how close you are before day 8. ## Questions ### Is there a free plan? No. Builder and Pro each start with a 7-day free trial instead. Without a plan you can add one site, see its preview audit of up to 6 pages, and export or delete your data. The free SEO tools on serpkin.com stay free and need no account. ### Will I be charged during the trial? No. A card is required to start, and the first charge is on day 8. Cancel before then in Account, under Billing, and you pay nothing. You keep access until the trial ends. ### How are missions counted? Each new mission Serpkin creates for your workspace in a calendar month counts once, whatever happens to it later. Missions you already have stay open, and you can keep working on and verifying them after you reach the limit. ### Do unused credits roll over? No. Each plan includes a monthly amount that resets on the 1st (UTC). Credits have no cash value. ### What happens to my data if I cancel? It stays. At the end of the trial or paid period the workspace has no plan: every site, mission, result and history entry is kept and readable, but scans, site watch and rank checks stop until you start a subscription. ## Related - [Credits: what research costs and how the monthly allowance works](https://serpkin.com/docs/credits): Credits - [Plans, payments and billing: change, pause or cancel at any time](https://serpkin.com/docs/billing): Billing - [Missions: what they are and how they're ranked](https://serpkin.com/docs/missions): Missions - [Site watch: regular rechecks and alerts](https://serpkin.com/docs/site-watch): Site watch --- # Credits: what research costs and how the monthly allowance works > Credits only pay for research that uses Serpkin's search data. Here is every price, what stays free, and what happens when the allowance runs out. Canonical: https://serpkin.com/docs/credits Updated: 2026-11-03 | 6 min read ## In short - Builder includes 500 credits a month and Pro 1,500, resetting on the 1st at 00:00 UTC with no rollover. The 7-day trial is capped at 150. - Only research with Serpkin's search data costs credits. Scans, missions, verification, site watch and Search Console are included. - Costs are fixed per operation, so you can estimate a session before your agent starts it. - Research that fails definitely is not charged, and every retry is idempotent. Credits pay for research that uses Serpkin's search data: keyword ideas, live search results, competitor research, keyword gaps, estimated rankings, AI answer checks, content briefs and backlink refreshes. Everything that reads your own site, your missions, your results or your Search Console data is included. This page lists the exact costs, how the monthly allowance works, and what happens when you run out. ## What uses credits Credits are spent per operation, at fixed prices, so you can estimate a research session before your agent starts it. The prices below come from the same table the server charges against. _Credits per research operation_ | Operation | Credits | Charged per | | --- | --- | --- | | Keyword research | 2 | seed | | SERP analysis | 1 | keyword | | Competitor research | 3 | request | | Keyword gaps | 3 | competitor | | Estimated rankings | 3 | site | | AI visibility check | 1 | query | | Content brief | 2 | brief | | Backlink refresh | 5 | refresh | A few examples make the arithmetic concrete. Keyword research for one seed phrase costs 2 credits. Analyzing three keywords costs 3. Finding gaps against two competitors costs 6. A visibility check for five queries costs 5. A single content brief costs 2. ## What is included Most of what Serpkin does every day does not touch your credits. These are included on every plan: - **Site scans and missions:** the crawl, the analysis and every mission Serpkin creates. - **Verification and measurement:** checking a mission on a preview or in production, then the 14 and 28 day results. - **Site watch and competitor watch:** the regular checks, alerts, early wins and the weekly email. - **Search Console:** connecting it, syncing queries and pages, and URL inspections. - **Rank tracking:** tracked keywords are checked on your plan's cadence at no credit cost. - **Monthly snapshots:** AI visibility and backlinks refresh on their own each month without spending credits. Estimated rankings refresh monthly only when monthly research is on, and use credits. - **AI content reviews:** these have their own monthly allowance, separate from credits. Reading is always free. Opening a saved content brief, viewing a stored snapshot or asking for the weekly summary costs nothing. Manual research and automatic initial/monthly topic research can spend credits. An initial automatic ranking estimate costs 3; seed keyword research costs 2. Included scheduled monthly snapshots remain separate and spend no credits. You can disable automatic topic research at registration or in Site details; queued work continues. Site and business-fit assessments use no search credits. Source files are attached only when a supported route map exists; a missing mapping does not make reading a saved report cost credits. Research-capable agent keys can also have a monthly credit ceiling, managed under Agents. Queued/running jobs reserve that key's budget; settled jobs count charged credits. It is an additional UTC-month limit inside the workspace allowance. A zero limit blocks credited research and a blank limit adds no extra ceiling. Site schedules and automatic topic research remain separate workspace work. Changing key access or limits affects new calls, not already accepted jobs. ## Your monthly allowance _Credits included per calendar month_ | Plan | Credits a month | Typical use | | --- | --- | --- | | Builder or Pro trial | 150 | A first research pass during the 7-day trial | | Builder | 500 | Weekly research for a handful of sites | | Pro | 1,500 | Daily research across many sites or client projects | During the 7-day free trial, research is capped at 150 credits. When the trial converts on day 8, the full allowance of your plan applies right away. A workspace without a plan has no research credits. The allowance resets on the 1st of each month at 00:00 UTC, on both monthly and yearly billing. Unused credits do not roll over, so there is no reason to hoard them. Your Account page shows the reset date in your local format and the exact number left. 1. **Reserved** When research starts, its cost is set aside so two jobs can't spend the same credits. 2. **Running** Reserved credits still count as unavailable while the provider works. 3. **Settled** On success the reservation becomes a charge. On a definite failure it is released. 4. **Reset** At the start of the next UTC month, the allowance returns to the full plan amount. _How a credit moves from available to spent_ Because reservations are visible, the number on your Account page can be lower than the number of credits you have actually spent. The page separates used credits from credits reserved for running research, so a slow job never looks like a mysterious charge. ## Check your balance In the app, open Account. The Credits panel shows remaining credits, the monthly total, a usage meter, the cost table and the operations that are included. Reserved credits appear next to used credits while a job is running. From a terminal, `npx serpkin status` prints the site, ownership, data level, next mission and credits in one view. Your agent can see the same numbers. Serpkin's MCP instructions tell it to read free data first, state the cost before spending credits, and ask you before a research operation. If you ask for something expensive, a well-behaved agent will say what it costs and wait. ## When you run out Research that would cost more than you have is refused before it starts, with a plain message: how many credits it needs, how many remain and the date they reset. The HTTP status is 402, and the error code is `CREDITS_EXHAUSTED`. Nothing partial is charged, and the rest of Serpkin keeps working: scans, missions, site watch, verification and Search Console are unaffected. Without a plan, research is refused with the error code `TRIAL_REQUIRED` and a link to start a trial. Reading research you already saved stays free. A monthly safety cap can also pause research for the rest of the month. During the trial the cap is lower. It exists to stop a runaway loop from producing a large provider bill. You see the same kind of message with the resume date, and your existing data, missions and checks continue. ## Failed research and refunds Credits are charged when the work succeeds. If a job fails before the provider is called, or fails definitely after a call, the reservation is released and nothing is charged. If a call finished but its result never arrived, the credits stay charged, because the provider did the work. That case is rare, and the job history shows it as an uncertain dispatch rather than a clean failure. Retrying a failed operation is safe. Each request carries an idempotency key, so a retry that reaches the server twice is treated as one request. If you see a charge you cannot explain, open the job in Account and check its status and timestamps before contacting support. ## Spend less without losing coverage _Ways to get more from the same allowance_ | Instead of | Try | | --- | --- | | Re-analyzing the same keywords every week | Use the stored SERP snapshot and rankings you already have | | Refreshing backlinks on a whim | Read the monthly snapshot first. A manual refresh costs 5 credits | | Building a new brief for every edit | Reuse the saved brief. Reading it is free | | Asking for ten competitor gap reports | Start with the two competitors that matter most, then widen | | Researching before the site is verified | Verify ownership first, so scan and Search Console missions can run without credits | ### What credits do not buy Credits are not a ranking guarantee, a traffic promise or a substitute for shipping the work. They buy data that makes a mission specific: the query, the page, the gap and the check. The change still has to be made in your repository and deployed by you. If you need more research than your plan includes, upgrade in [Billing](https://serpkin.com/docs/billing). Plan limits, including credits, are listed together in [Plans and limits](https://serpkin.com/docs/plans-and-limits). ## Questions ### Do credits roll over to next month? No. The allowance resets on the 1st at 00:00 UTC. Unused credits do not carry over, so spend them on the research that helps this month. ### Does verifying a mission cost credits? No. Verification, measurement, site watch, competitor watch, rank tracking and Search Console syncs are included on every plan. ### Why were credits reserved but not charged? A running research job sets its cost aside so two jobs cannot spend the same credits. When it finishes, the reservation becomes a charge or is released on failure. ### Can I buy extra credits? Not separately. Credits come with the plan, and upgrading raises the monthly allowance immediately. During the trial, the cap is 150 credits until day 8. ## Related - [Plans and limits](https://serpkin.com/docs/plans-and-limits): Plans and limits - [Plans, payments and billing: change, pause or cancel at any time](https://serpkin.com/docs/billing): Billing - [MCP tools and prompts reference](https://serpkin.com/docs/mcp-tools): MCP tools - [Missions: what they are and how they're ranked](https://serpkin.com/docs/missions): Missions --- # Connect Google Search Console for real queries and measured results > Search Console gives missions real queries and gives results a real baseline. Connect it once, read-only, and Serpkin syncs it daily. Canonical: https://serpkin.com/docs/search-console Updated: 2026-10-30 | 6 min read ## In short - Serpkin asks for read-only Search Console access and syncs a connected property about once a day. - It reads the current 28 days and the previous 28, plus 90 days of daily data for charts and trends. - A verified property proves ownership and unlocks full scans and site watch. - Disconnecting revokes the token at Google and deletes the stored tokens and synced data for that site. Connecting Google Search Console turns Serpkin from a scanner into a system that knows what people actually search for and which pages already get impressions. Missions then target real queries, results are measured with the same data, and ownership is verified without a file. Access is read-only. This page covers what Serpkin reads, how often it syncs, what the two date windows mean, and how to fix a connection that needs attention. ## Why connect it - **Real queries, not guesses:** missions come from the searches that already show your pages, including queries you rank for on page two or three. - **Measured results:** after you verify a mission, Serpkin compares clicks, impressions and position with the previous period instead of relying on a rank estimate. - **Ownership:** a verified Search Console property proves the site is yours, which unlocks full scans, site watch and competitor watch. - **Indexing detail:** URL inspections show whether a page is indexed, its coverage state and when Google last crawled it. Without Search Console, Serpkin still works: foundation missions come from its own crawl, growth missions from keyword research, and you can verify ownership with a file instead. For a new site, though, Search Console is usually the only data there is. Third-party search data rarely knows a young domain, while Search Console already lists the searches your pages appear in, including the ones on page 2 or 3 that are closest to winning. ## Connect a property 1. **Open the site's Search Console panel** In the app, open the site and find the Search Console section under site settings. Choose Connect Search Console. Serpkin sends you to Google with a short-lived, single-use request tied to your signed-in session. 2. **Pick the Google account that owns the property** Use an account that has Owner, Full or Restricted access to the property. The property has to exist in Search Console already. If the site is not there, add it in Search Console first, then come back. 3. **Approve read-only access** Serpkin asks for the `webmasters.readonly` scope. It can read your properties and performance data and cannot change settings, submit sitemaps or alter your site. The token is encrypted at rest. 4. **Wait for the first sync** Serpkin matches the site to a property and starts the first sync. Missions update when it finishes, usually within a few minutes. The panel shows the property, your access level and the last sync time. If Google has no property for the site under that account, the connection fails with a message that says so. This is the most common setup problem, and it is fixed in Search Console, not in Serpkin. Add the exact site (domain property or URL prefix) and reconnect with the same account. ## What Serpkin reads _Search Console data Serpkin stores for a connected site_ | Data | Window | Used for | | --- | --- | --- | | Queries and pages | Current 28 days and the 28 days before, up to 25,000 rows per period | Finding pages near page one, queries with high impressions and low clicks, and period comparisons | | Pages | The same two periods | Choosing which pages a mission should change | | Daily site series | 90 days ending at the current window | Charts and trend detection on the Results page | | Daily query series | 90 days for the top 50 queries by impressions | Showing whether a specific query moved after a fix | | URL inspection | Up to 20 pages per property per UTC day | Checking indexing, coverage state and last crawl time | The current window ends two days ago, because Google's performance data has a lag. The previous window is the 28 days before that. Comparing the two avoids the trap of calling a normal weekly dip a regression. The daily series uses the same end date, so charts and totals agree. ### What it does not read Serpkin does not read your Search Console users, your sitemaps, your settings or your removals. It does not ask for write access, and it does not use Google data to build a profile of you. The data is used to produce your missions, results and charts, which is the limited use Google's API terms require. ## How missions use the data 1. **Find the signal** A query with impressions on page two, a page with a falling click-through rate, or a page that lost position. 2. **Add the page** The query is tied to the page that ranks for it, and the route map adds the source file. 3. **Explain why now** The mission quotes the numbers and the period they come from, not a generic tip. 4. **Measure after** Verification records a baseline, and results compare the same query and page at 14 and 28 days. _From a Search Console row to a mission your agent can act on_ A site needs at least 100 impressions over 28 days before Search Console drives missions. Below that, there is not enough signal to separate a real opportunity from noise, so Serpkin falls back to its own scan, estimated rankings and new-site sources. The panel says which data level the site is on, and it changes on its own as impressions grow. ## Sync, lag and freshness Serpkin syncs a connected property about once a day. The sync replaces the stored snapshot in one transaction, so a page never shows half of an old period and half of a new one. If Google is slow or returns an error, the previous snapshot stays in place and the last sync time does not move. Expect a two-day lag in the data itself. A change you deploy today cannot appear in Search Console performance until Google has crawled it, indexed it and reported the impressions, which can take days or weeks. That is why verification checks the page directly, while results wait 14 and 28 days before drawing a conclusion. > **Brand new sites** > > A new site can be verified in Search Console and still have almost no performance rows. Serpkin will use search data and its own crawl for missions until impressions arrive. This is normal, not a broken connection. ## When the connection needs attention _Connection states and what they mean_ | State | What happened | What to do | | --- | --- | --- | | Connected | The token works and the last sync succeeded | Nothing. Check the last sync time if data looks stale | | Needs reconnect | Access expired, was revoked, or the property permission was removed | Reconnect with an account that still has access. Earlier data is kept | | Not connected | No property has been connected for this site | Connect one, or verify ownership with the file method | | Unavailable on this server | The server has no Google OAuth credentials configured | Use the file verification method, or ask the operator to configure Google access | A reconnect does not throw away history. The stored rows remain, but new missions stop using them until the connection works again, so a revoked token cannot silently feed stale decisions. Reconnecting resumes the daily sync and refreshes the snapshot. If the property list shows several similar properties, choose the one that matches your canonical host. A`sc-domain:` property and a URL-prefix property can both exist, and their numbers differ. Serpkin uses the property you connected, so pick the one you actually report on. ## Disconnect and delete the data Disconnecting in the site panel revokes the token at Google and deletes the stored tokens and synced Search Console data for that site. It does not delete your site, missions or results. You can also remove Serpkin's access from your Google account page, which has the same effect the next time Serpkin tries to sync. If you delete your Serpkin account, the connection and its data go with it. The [privacy policy](https://serpkin.com/legal/privacy) lists retention for everything else, including the audit log. ## Privacy and Google's rules Search Console access is read-only and encrypted at rest with AES-256-GCM. Serpkin does not sell Google data, use it for advertising, or transfer it to third parties except the processors that run the service. Selected query text can also be used for contextual topic assessments and AI content reviews, alongside public page excerpts and business context, through OpenRouter and a model provider that does not store requests for training. Clicks, impressions, account details and the rest of your Search Console data are never sent there. For the full picture, including how to export or delete your data, see [Data and privacy](https://serpkin.com/docs/data-and-privacy). ## Questions ### Does Serpkin need write access to Search Console? No. It uses the read-only webmasters scope. It cannot change settings, submit sitemaps or modify your site. ### Why does the data end two days ago? Google's performance data has a lag. Serpkin ends the current 28-day window two days ago so the totals are complete and the comparison with the previous period is fair. ### Can I use Search Console without connecting Google? You can verify ownership with a file and use scans, estimated rankings and search data. Search Console is what adds your real queries, clicks and impressions. ### What happens to my data if I disconnect? Serpkin revokes the token at Google and deletes the stored tokens and synced Search Console data for that site. Your site, missions and results stay. ## Related - [Getting started with Serpkin](https://serpkin.com/docs/getting-started): Getting started - [Verification and results](https://serpkin.com/docs/verification-and-results): Verification and results - [Your data and privacy: what Serpkin stores, and how to remove it](https://serpkin.com/docs/data-and-privacy): Data and privacy - [Troubleshooting: setup, scans, verification and weekly runs](https://serpkin.com/docs/troubleshooting): Troubleshooting --- # Plans, payments and billing: change, pause or cancel at any time > Start with a 7-day free trial of Builder or Pro. This guide explains pricing, the trial, and how plan changes, cancellations and refunds work. Canonical: https://serpkin.com/docs/billing Updated: 2026-11-03 | 6 min read ## In short - Builder is $29 a month or $290 a year. Pro is $79 a month or $790 a year. - Creem is the merchant of record: it charges the card, handles tax and issues invoices. Serpkin never stores card details. - Each workspace gets one 7-day free trial. A card is required, and you are charged on day 8 unless you cancel before then. - Plan changes happen in place with proration, so you are never double-billed. - Pause or cancel at the end of the trial or paid period. Your sites, missions and history stay either way. > **Paid checkout is not open yet.** > > No payment is collected while checkout is closed, and new workspaces start on the current Free plan. The sections below describe how billing and the free trial work once checkout opens. [Sign in](https://serpkin.com/login) and check Account for current availability. Serpkin has two plans, Builder and Pro, billed monthly or yearly. Each starts with a 7-day free trial. Payments are handled by Creem, our merchant of record, which charges your card, collects any sales tax or VAT and issues your invoices. You can change plans, pause or cancel at the end of a paid period, and none of it deletes your data. This page covers the money side; what each plan includes is in [Plans and limits](https://serpkin.com/docs/plans-and-limits). ## Prices _Plan prices in US dollars_ | Plan | Monthly | Yearly | Yearly saves | | --- | --- | --- | --- | | Builder | $29 | $290 | 2 months free | | Pro | $79 | $790 | 2 months free | Yearly billing costs ten monthly payments, so the two free months are built into the price rather than a temporary discount. Allowances are the same on monthly and yearly billing, and credits still reset every month. Prices are in US dollars. Creem adds the sales tax or VAT that applies where you are, and shows the total before you pay. ## The 7-day free trial _How the trial works_ | | During the trial | From day 8 | | --- | --- | --- | | Price | $0 | The plan and period you chose | | Features | Everything in the plan | Everything in the plan | | Research credits | Capped at 150 | The full monthly allowance | | If you cancel | No charge; access until the trial ends | Access until the paid period ends | A card is required to start. Creem charges it on day 8 unless you cancel before then. To cancel, open Account, then Billing, or use the Creem customer portal. A trial you cancel is never charged, and you keep access until the 7 days are up. After that the workspace has no plan. Each workspace gets one trial. If you come back later, Start subscription begins a paid plan right away, with no second trial. Account shows "Your trial was already used" in that case. ## Start a trial or a subscription 1. **Choose a plan and a billing period** Open Account, then Plan and billing. Pick Builder or Pro and switch between Monthly and Yearly. The card shows the price for the period and, for yearly, the approximate monthly equivalent. 2. **Enter your card with Creem** Choosing a plan opens Creem's checkout in a secure page. Creem takes the card details and handles tax. On a trial, nothing is charged until day 8. Serpkin never sees or stores your card number. 3. **Come back to your workspace** Creem returns you to Account while Serpkin checks your actual plan. Returning from checkout alone does not confirm payment. When access is ready, Continue to your task returns to the site or mission you were reviewing. A delayed confirmation can be checked again; your saved work stays available. No scan or research starts automatically. If you already have a subscription, buying again does not create a second one. Serpkin changes the existing subscription in place through Creem, so you cannot be double-billed by clicking twice. Offers shown beside an audit or a limit explain the specific extra capacity and keep that task attached to checkout for up to 30 days. You can compare both plans before choosing. A larger scan allowance does not guarantee a useful mission or a ranking improvement. ## Change plan or billing period Upgrades, downgrades and switches between monthly and yearly all happen in place. Creem applies proration and charges the difference immediately, so the new allowance is available at once. Moving from yearly to monthly mid-term credits the unused part of the year against the new period. The confirmation page and your invoice show the exact amount. 1. **You choose** Pick the plan and period in Account. The price updates before you confirm. 2. **Creem prorates** Unused time is credited and the difference for the new plan is charged now. 3. **Plan switches** A webhook updates the workspace. New limits and credits apply immediately. 4. **Invoice follows** Creem issues the invoice and emails it to the address on the billing account. _What happens when you change plan_ If a scheduled pause or cancellation is pending, choosing a plan resumes the subscription first and then applies the change. That is deliberate: a plan change should not leave the workspace scheduled to lose its plan. ## Pause or cancel _Pause and cancel compared_ | | Pause | Cancel | | --- | --- | --- | | When it takes effect | End of the period you have paid for | End of the period you have paid for | | What you keep | Every site, mission, result and history | Every site, mission, result and history | | Can you undo it | Yes, resume in one click and billing restarts | Yes, before the period ends, or choose a plan again later | | Afterwards | No plan: data kept and readable, subscription kept for an easy return | No plan: data kept and readable, subscription ended | Both options are in Account under Plan and billing. Pause is for a break: the subscription stays resumable and your paid plan returns when you resume. Cancel is for a clean end: the subscription stops and you can delete the account later if you want. If the subscription is already paused, cancelling ends it immediately, because there is no paid period left. You keep the paid plan until the period ends, including credits and limits. Serpkin does not cut you off on the day you click pause or cancel. The Account page shows the exact end date. ## If a payment fails A failed renewal puts the subscription in `past_due`. Your paid plan stays active while Creem retries the payment, so a card that expired over the weekend does not immediately lock you out of work in progress. The Account page shows a warning and a link to the billing portal, where you can update the card. If the retries fail and the subscription becomes unpaid or expires, the workspace has no plan. Nothing is deleted: every site, mission, result and history entry stays readable. Scans, site watch, rank checks and alerts stop until you start a subscription again. ## Invoices, receipts and cards Manage billing opens the Creem customer portal. There you can update the card, change the billing email, download invoices and see the next charge. Serpkin does not proxy card changes through its own forms, which keeps payment details out of the app entirely. The billing email can differ from your sign-in email. Use the address your finance team needs on the invoice. If you change companies, update the billing email before the next renewal so the invoice reaches the right inbox. ## Refunds Creem pays refunds back to the original payment method. The [refund policy](https://serpkin.com/legal/refunds) explains the first-payment window, what happens with renewals, and the cases where a refund is always given, such as a duplicate charge or a serious outage on our side. Credits included with a plan have no cash value and are not refunded separately. To request a refund, contact us from the email address on the Serpkin account. Include the invoice or the date of the charge, and say whether you want the subscription cancelled as well. A full refund cancels the subscription and the workspace has no plan, with all data kept. A trial has nothing to refund, because nothing is charged before day 8. ## What happens after a trial or plan ends - **Your data stays:** sites, missions, results, history and reports are not deleted when a trial or plan ends. - **The workspace is read-only:** you can open everything you saved, export it or delete it. - **Work stops:** no new missions, scans, research, site watch, rank checks, digests or alerts. Unused credits do not carry over. - **Your agent is told why:** blocked actions return `TRIAL_REQUIRED` with a link to start a subscription. - **You can come back:** Start subscription restores the plan's limits immediately. A second trial is not available. Cancelling is not the same as deleting your account. If you want your data removed, export it first, then delete the account from Account settings. The [data and privacy](https://serpkin.com/docs/data-and-privacy) page lists what is deleted and what is kept for security. ## Common billing questions ### Can I pay yearly after starting monthly? Yes. Switch to Yearly in Account and Creem prorates the change. You get the yearly price and the unused part of the current month is credited. ### Do you offer invoices with a VAT number? Creem issues the invoice and handles tax. Add your tax details in the customer portal so they appear on future invoices. For past invoices, the portal has the documents already issued. ### What if I cancel by mistake? Before the period ends, choose Keep my plan in Account and the scheduled cancellation is removed. If the subscription is already paused, Resume restarts billing and restores the paid plan once Creem confirms. > **Pause before a quiet month** > > If you will not ship SEO work for a few weeks, pause instead of cancelling. The subscription stays resumable, your data stays, and you avoid setting everything up again when work restarts. ## Questions ### Does cancelling delete my data? No. At the end of the trial or paid period the workspace has no plan. It keeps every site, mission, result and history entry, read-only. Deleting the account is a separate action. ### Do I pay anything during the free trial? No. A card is required, but Creem charges it on day 8. Cancel before then in Account, under Billing, or in the Creem portal, and you pay nothing. ### Can I switch from monthly to yearly? Yes. Choose Yearly in Account and Creem prorates the change, crediting the unused part of the current period. ### What happens if my card fails? The subscription goes to past_due and the paid plan stays active while Creem retries. Update the card in the billing portal so the workspace keeps its plan. ### Who issues the invoice? Creem, as merchant of record. It also collects sales tax or VAT and emails the invoice to the billing address you set in the portal. ## Related - [Plans and limits](https://serpkin.com/docs/plans-and-limits): Plans and limits - [Credits: what research costs and how the monthly allowance works](https://serpkin.com/docs/credits): Credits - [Your data and privacy: what Serpkin stores, and how to remove it](https://serpkin.com/docs/data-and-privacy): Data and privacy - [Troubleshooting: setup, scans, verification and weekly runs](https://serpkin.com/docs/troubleshooting): Troubleshooting --- # Your data and privacy: what Serpkin stores, and how to remove it > The practical version of the privacy policy: what is collected, who processes it, how long it stays, and how to take it with you or delete it. Canonical: https://serpkin.com/docs/data-and-privacy Updated: 2026-10-30 | 6 min read ## In short - Serpkin never receives your source code. The CLI uploads a route map of URL paths and file names only. - Search Console access is read-only, tokens are encrypted with AES-256-GCM, and the data is used only for your missions and results. - Fetched evidence expires in 7 to 30 days; account data stays until you delete it. - You can export your workspace as JSON and delete your account in the app, after cancelling any live subscription. Serpkin needs enough data to find SEO work, hand it to your agent and check the result. It does not need your source code, and it does not sell data or run ads. This page explains what is stored, how long it is kept, who processes it, and how to export or delete it. The legal terms are in the [privacy policy](https://serpkin.com/legal/privacy); this page is the practical version. ## What Serpkin stores - **Your account:** name, email, a password hash and session records. Agent keys are stored as hashes, so the key is shown once and never again. Each key can have read, research, implementation or full access and an additional monthly research-credit ceiling. Keys are workspace-bound; these roles are not per-site isolation. - **Your workspace:** sites, public URLs, business description, audience, country, language, saved business briefs and your corrections. - **Missions and results:** the missions Serpkin created, the changes your agent submitted, the verification checks and the measurements at 14 and 28 days. - **Site evidence:** extracted metadata and short main-content excerpts from public pages, page inventory and coverage assessments, search results, competitor sitemap entries and the checks it ran. This is what a mission points at. - **Operational records:** jobs, audit events, technical logs and product analytics, with secrets redacted. Activation events distinguish audit readiness, audit views, recommendation handoffs and mission starts. These events do not receive setup prompts, page text, keywords or credentials. You do not upload a database dump or a copy of your repository. Serpkin builds its picture from public URLs and, if you connect it, Search Console. ## Your source code stays yours The CLI can upload a route map: a list of URL paths and the file names that render them, such as `/pricing` to `app/pricing/page.tsx`. That is how a mission can name the file to edit. The route map contains paths and file names, not file contents. Serpkin never receives your source code, your git history, your environment variables or your secrets. Your coding agent works in your repository on your machine or in your CI. It reads the mission from Serpkin and makes the change locally. The code never passes through Serpkin's servers. ## Search Console data If you connect Search Console, Serpkin asks for read-only access and stores the queries, pages, clicks, impressions, positions and URL inspection results it needs for missions and results. OAuth tokens are encrypted at rest with AES-256-GCM. Disconnecting revokes the token at Google and deletes the stored tokens and synced data for that site. Google's API terms impose Limited Use obligations. Serpkin uses Search Console data only to provide the features you see: missions, results, charts and reports. It does not sell the data, use it for advertising, or let humans read it except for security, support at your request, or where the law requires it. ## Who processes your data _What each processor receives_ | Processor | Purpose | What it receives | | --- | --- | --- | | Hosting and database providers | Run the service and store your workspace | The data described above, encrypted in transit and at rest | | Creem | Payments, tax and invoices | Billing name, email, company details and payment data. Serpkin never sees card numbers | | Email provider | Sign-in, alerts and the weekly summary | Your email address and the content of those emails | | Search data provider | Keyword, SERP, competitor, AI visibility and backlink research | The query text and market needed for the research you request | | OpenRouter and its model providers | Business assessments, topic relevance checks and advisory content reviews | Bounded public page excerpts, saved business context and selected query text; content reviews also use the page brief. No source code, account credentials or Search Console metrics | Business assessments and AI content reviews are routed only to providers that do not store requests for training. The search data provider receives the queries you ask about, not your site's private analytics. A current list of providers is available on request. Some providers process data outside your country, including outside the EEA and the UK. Where they do, Serpkin relies on adequacy decisions or standard contractual clauses. ## How long data is kept _Retention windows_ | Data | Kept for | | --- | --- | | Account, sites, missions and results | Until you delete your account | | Saved audit briefs, page inventory and public content excerpts | Until you delete your account; the latest assessment is updated on rescan | | Search Console tokens and synced data | Until you disconnect the site or delete your account | | Fetched page and search evidence | 7 to 30 days depending on the type, then deleted | | Finished jobs | 90 days | | Idempotency and webhook records | 30 days | | Site info events | 180 days. Alerts and wins are kept because they feed the value record | | Audit log | 365 days, including after account deletion | | Product events | 400 days, or until you delete your account | | Database backups | About 14 days, then they roll over | Retention is enforced by a scheduled purge, not by hand. Evidence past its expiry stops being served immediately, even before the purge removes the row. Deleting a workspace removes its sites and records; the security audit log and rolling backups are the two exceptions, and both are time limited. ## Export or delete your data 1. **Export first** Account settings has a JSON export of your workspace: sites, missions, results, history and settings. Download it before deleting anything. The export does not include credentials or other people's data. 2. **Cancel a live subscription** If a paid subscription is running or paused, cancel it in Plan and billing first. Deleting an account with a live subscription would leave a charge nobody can manage. The subscription has to be ended before deletion. 3. **Confirm deletion** Deleting the account asks for your password. Serpkin then deletes the workspace, its sites and all their data, and the user account. The audit record that the account was deleted is kept for up to 365 days. > **Deletion is not reversible** > > There is no restore after the confirmation. Rolling backups drop the data as they expire, so export anything you might need before you delete. ## How it is protected Traffic uses TLS. Google tokens are encrypted with AES-256-GCM using a key separate from the database. Passwords and agent keys are stored only as hashes. Backups are encrypted with a separate key. Production access is limited to the people who run Serpkin. Rate limits mostly store a one-way digest of your IP address rather than the address itself. The sign-in system keeps the IP address with the request path to stop credential stuffing, and deletes it after one day. Technical logs redact secrets. If a breach affects you, Serpkin tells you as the law requires. ## Your rights You can ask to access, correct, delete or export your personal data, and to restrict or object to how it is used. Where processing relies on consent, you can withdraw it at any time. Most of this is self-service in the app; anything else goes to the contact address on the [About page](https://serpkin.com/about), and Serpkin replies within one month. Under the CCPA you can ask what personal information is collected, used or disclosed, and ask for deletion or correction. Serpkin does not sell personal information or share it for cross-context behavioural advertising, and it will not treat you differently for exercising these rights. ## Changes and questions If the privacy policy changes in a meaningful way, account holders are emailed before the change takes effect. Questions about data, a processor or a deletion go to the contact address on the [About page](https://serpkin.com/about). For payment records, the invoice in the Creem portal is the fastest source. 1. **Public data** Serpkin reads public pages and search results to build missions. 2. **No source code** Only a route map of paths and file names is uploaded. 3. **Limited use** Search Console data serves your missions and results, nothing else. 4. **You stay in control** Export or delete from Account, and disconnect Google at any time. _The short version_ ## Questions ### Does Serpkin upload my repository? No. The CLI uploads a route map of URL paths and the file names that render them. File contents, git history and environment variables stay on your machine. ### Do you sell my data or use it for ads? No. Serpkin does not sell personal information and does not share it for cross-context behavioural advertising. ### How do I delete everything? Cancel any live subscription, download the JSON export if you want a copy, then delete the account in settings. The workspace, sites and data are deleted immediately. The audit log and backups expire on their own. ### Is my Search Console data used for AI training? No. Assessments and reviews are routed only to providers that do not store requests for training. They use bounded public page excerpts, saved business context and selected query text; content reviews also use the content brief. Source code and Search Console metrics are not sent. ## Related - [Connect Google Search Console for real queries and measured results](https://serpkin.com/docs/search-console): Search Console - [Plans, payments and billing: change, pause or cancel at any time](https://serpkin.com/docs/billing): Billing - [Plans and limits](https://serpkin.com/docs/plans-and-limits): Plans and limits - [Troubleshooting: setup, scans, verification and weekly runs](https://serpkin.com/docs/troubleshooting): Troubleshooting --- # Troubleshooting: setup, scans, verification and weekly runs > The five things that cause most problems, in the order worth checking, with the exact message and the fix. Canonical: https://serpkin.com/docs/troubleshooting Updated: 2026-11-03 | 8 min read ## In short - Run npx serpkin status first. It separates a key or server problem from a local agent or deploy problem. - Serpkin needs Node 22 or newer, and an agent must restart after setup to see the MCP server. - A 401 on a preview is usually deployment protection, not a broken mission. - When asking for help, include the site id, error code and run URL, and never include a key or token. Most Serpkin problems are one of five things: an old Node version, a key that was revoked, a site that is not verified, a preview that is protected, or a plan limit. This page walks through each in the order worth checking, with the exact message you will see and the fix. If none of it matches, the last section says what to send us. ## Start with these three commands Before changing anything, collect the state. These commands are safe and print no secrets. _First diagnostics_ | Command | What it tells you | | --- | --- | | `node --version` | Whether you are on Node 22 or newer, the minimum the CLI supports | | `npx serpkin status` | The site, ownership state, data level, next mission and credits | | `npx serpkin --version` | The CLI version, so we can tell whether an update fixes it | If a command fails, copy the whole error, not just the last line. Serpkin errors usually include the fix in the message. Never paste an agent key, an Anthropic key or a password into a support message. ## Setup and sign-in problems ### The command does nothing, or npx downloads an old version Check Node first. Serpkin needs Node 22 or newer. If you use a version manager, switch to a current LTS release and run the command again. A stale npx cache can also serve an old package; `npx serpkin@latest` forces a fresh download. ### The browser code expired The sign-in code is short lived. If the browser page says it expired, run `npx serpkin` again and approve the new code. Make sure the code in the terminal matches the code in the browser before approving: that match is what stops someone else from approving a login they did not start. ### The key is invalid or revoked A 401 means the agent key is missing, revoked or belongs to another workspace. Run `npx serpkin init --login` to sign in again, or create a new key in Agents, and set it as `SERPKIN_API_KEY`. Revoking an old key is the right move if it was ever pasted into a chat, a commit or a log. ### The wrong server is configured `.serpkin.json` stores the server and site id. If you moved from a self-hosted server to serpkin.com, or the other way around, pass `--server` explicitly or remove the file and run setup again. The CLI asks before it switches servers when the file and the flag disagree. ## Your agent cannot see Serpkin Setup connects the agents it finds, but an already-running agent will not pick up a new server until it restarts. Quit and reopen Claude Code, Cursor or Codex, then check the connection. _Where each agent keeps the connection_ | Agent | What setup writes | How to check | | --- | --- | --- | | Claude Code | The Serpkin plugin, or a project MCP entry | Run /mcp in a session and look for serpkin | | Cursor | .cursor/mcp.json and a project rule | Open Cursor settings, MCP, and confirm serpkin is connected | | Codex | ~/.codex/config.toml and a section in AGENTS.md | Start a new session and ask what SEO to do | If the entry exists but calls fail with 401, the key in that config is stale. If calls fail with a network error, check a proxy or firewall that blocks the Serpkin server. Corporate TLS inspection can also break the CLI; configure your proxy's certificate or use a network that does not inspect traffic. In Claude Code, `/serpkin:next` is the fastest test. In any agent, ask "What should I do for SEO?" and watch whether it calls a Serpkin tool. If it answers from general knowledge without calling a tool, the server is not connected. ## Scans and indexing problems ### The site is unverified, so only a few pages are read Until ownership is proven, a scan is a preview: the homepage plus up to five same-origin pages linked from it. Verify with Search Console, a TXT record or the verification file to unlock full scans and site watch. See [Getting started](https://serpkin.com/docs/getting-started). ### Pages are missing from the scan A page is skipped when robots.txt disallows it, it returns a non-200 status, it needs a login, or it is only reachable through JavaScript navigation. Check the page in a private window with JavaScript off. If the content is empty, the page is client-rendered; Serpkin can render a limited number of pages on paid plans, but the server HTML still matters because that is what Google sees first. ### The preview is unreachable Deployment protection returns 401 or 403. Allow Serpkin through it, or check a public preview. Previews must be on your own domain or a subdomain, or on `*.vercel.app`, `*.netlify.app` or `*.pages.dev`. A URL on another host is refused before any request is made. ### robots.txt blocks the check If robots.txt disallows SerpkinBot, the tool reports it instead of fetching the page. That is the correct behaviour. Remove the rule for the paths you want checked, or test with a URL that is allowed. ### The audit is incomplete or needs a business brief A crawl-limit status is different from a temporary failure. If the site has more discovered pages than your full-scan allowance, repeating the same scan will hit the same limit. Keep using checked-page technical findings and review [crawl and rendering limits](https://serpkin.com/docs/plans-and-limits#crawl-coverage). For JavaScript-dependent pages, make their main content available in server HTML or review supported rendering capacity. Only retry after changing the condition that blocked coverage. Open **Site → Site audit**. A preview needs ownership verification before a full scan; repeating the preview does not unlock content recommendations. If the full crawl hit a page/time limit, could not read pages, or needs JavaScript rendering, address that coverage issue first. A scan-allowance message tells you when scans reset. Saved findings remain available. A complete crawl can still ask for a brief review. Confirm the product, audience and specific search topics; exclusions prevent unrelated suggestions. Your draft survives background refreshes. Without automatic contextual assessment, only exact topics you confirm can qualify; demand and coverage checks still apply. Fully covered topics and weak suggestions are skipped rather than replaced with filler. ## No missions, or the wrong ones - **Everything is done:** the queue may be empty because open missions were completed, dismissed or resolved, or because no candidate has enough evidence and business fit. A scan or data refresh may find another change; it does not have to. - **The site is watch-only:** after a downgrade from Pro to Builder, extra sites keep their history and site watch but get no new scans, research or verification. Upgrade again to unlock them. - **The workspace has no plan:** before a trial, or after a trial or subscription ends, you see the preview audit and saved data but get no missions. Start a trial (or Start subscription if you already used it) in Account. - **The data level is low:** a new site without Search Console and without rankings gets foundation fixes from the scan first. Connect Search Console to unlock query-driven missions. - **A mission was dismissed:** dismissed missions stay hidden for 180 days. Restore one from the site's mission list if you want it back. Missions are ranked, not random. If the top mission looks small, it is usually because it blocks indexing or because it is already in progress. Finishing it moves the queue forward faster than skipping it. ## Verification fails _Common verification failures_ | What you see | Likely cause | Fix | | --- | --- | --- | | HTTP 401 or 403 | The preview is behind deployment protection | Allow Serpkin through, or verify on production after deploying | | The page still shows the old version | The deploy or CDN cache has not updated | Wait for the deploy, purge the cache, then verify again | | A check says noindex | The page or a header adds noindex | Remove it, or accept it if the page should not be indexed | | Canonical points elsewhere | A template or CMS setting overrides it | Make the canonical absolute and self-referencing | | Title, description or H1 missing | The change did not reach the rendered page | Check the deployed HTML, not only the source file | | Sitemap or robots.txt fails | The file is missing, invalid or blocked | Fix the response, then verify again | Verification keeps its history, so a failed attempt does not erase the mission. Fix what the checks reported and run it again. For a preview check from the terminal, `npx serpkin check ` exits 1 on regressions and 2 on errors, which makes it usable as a CI step. ## Search Console problems ### No property found The Google account you approved must already have access to the property. Add the site in Search Console with that same account, then reconnect. Domain properties and URL-prefix properties are different; connect the one you actually use. ### Needs reconnect Access expired, was revoked, or the property permission was removed. Earlier data is kept but no longer used for new missions. Reconnect from the site panel and the daily sync resumes. ### Connected but the numbers look old Search Console data lags by about two days, and Serpkin ends its 28-day window two days back for that reason. A brand new site can also have fewer than 100 impressions over 28 days, in which case missions use scan and search data until traffic grows. ## Limits, credits and pauses When an action would exceed a plan limit, Serpkin refuses that action and says which limit it hit and what the next plan includes. Nothing is deleted and existing work keeps running. Credits reset on the 1st at 00:00 UTC; missions, scans and reviews reset on the same schedule. `TRIAL_REQUIRED` means the workspace has no plan. The message includes a checkout link: "Start your 7-day free trial to get missions", with no charge until day 8. If the workspace already used its trial, Account offers Start subscription instead. Your saved data stays readable either way. A 402 with `CREDITS_EXHAUSTED` means the research costs more than you have left. A `SEARCH_DATA_PAUSED` message means a monthly safety cap is reached (it is lower during the trial); it gives the resume date. In both cases, scans, missions, site watch and Search Console keep working. [Credits](https://serpkin.com/docs/credits) has the full table. ## Weekly pull requests _Weekly workflow problems_ | Symptom | Fix | | --- | --- | | The run skips with a notice | A pull request labeled serpkin is still open. Review or close it | | No open mission | Nothing to do yet. Wait for the next scan or data refresh | | 401 from Serpkin | Set SERPKIN_API_KEY again with a fresh key for this workspace | | CI did not run on the PR | Add the optional SERPKIN_PR_TOKEN secret, or run CI by hand | | The change touched files the workflow does not allow | Nothing was pushed and the mission was dismissed. Restore it and make that change yourself | | The schedule stopped | Public repositories disable scheduled workflows after 60 days without activity. Run it once by hand | The run summary explains which job stopped and why. Read it before changing secrets; most failures are a missing variable, not a broken workflow. Setup details are in [Weekly pull requests](https://serpkin.com/docs/weekly-pull-requests). ## Billing problems If the plan did not change after payment, refresh Account once. Creem's webhook usually arrives within seconds but can be delayed. If a renewal failed, the subscription is in `past_due` and the paid plan stays active while Creem retries; update the card in the billing portal. A trial shows as trialing until day 8; if you cancel during the trial, nothing is charged and access ends with the trial. Invoices and receipts are in the same portal. See [Billing](https://serpkin.com/docs/billing). ## If it is still broken 1. **Reproduce it once** Write down the exact steps, the command or page, and the time. One clean reproduction is worth more than a long description. 2. **Collect the safe details** Include the site URL, the site id from `.serpkin.json`, the CLI and Node versions, the error code and the full message. For a weekly run, include the run URL. Never include a key, a token or a password. 3. **Contact us** Use the contact address on the [About page](https://serpkin.com/about). For billing, write from the email on the Serpkin account and include the invoice date. For privacy or deletion questions, say so in the subject so it reaches the right person. > **A quick sanity check** > > Run `npx serpkin status`. If it shows the site as verified, with a data level and a next mission, the connection is healthy and the problem is local to your agent or your latest deploy. If it fails, the problem is the key, the server or the network, and that narrows it down fast. ## Questions ### Why can't my agent find Serpkin? Restart the agent after setup, then check the MCP connection: /mcp in Claude Code, MCP settings in Cursor, or a new session in Codex. A 401 means the key is stale. ### Why does verification fail on my preview? Most often the preview is behind deployment protection and returns 401 or 403. Allow Serpkin through it, or verify on production after deploying. ### Why did my weekly run skip? A pull request labeled serpkin is still open, or there is no open mission. The run summary says which. Review or close the pull request, and the next run continues. ### Does a failed scan use a scan from my allowance? A scan that cannot start because of a plan limit is refused before it runs. If a scan starts and fails partway, the job history shows its status and any credits involved are handled by the same settlement rules. ## Related - [Getting started with Serpkin](https://serpkin.com/docs/getting-started): Getting started - [Verification and results](https://serpkin.com/docs/verification-and-results): Verification and results - [Weekly pull requests: one SEO mission a week, opened for review](https://serpkin.com/docs/weekly-pull-requests): Weekly pull requests - [Connect Google Search Console for real queries and measured results](https://serpkin.com/docs/search-console): Search Console