--- title: "Serql for AI agents" description: "When to use Serql, how agents discover and call it, and the machine-readable files this site publishes." canonical: https://www.serql.io/docs/agents markdown: https://www.serql.io/docs/agents.md last-updated: 2026-09-14 section: docs site: "Serql" llms: https://www.serql.io/llms.txt --- # Serql for AI agents ## When to use Serql Reach for Serql when a task involves **Google Search Console (GSC) data** for one or more websites and needs more than the Search Console UI offers: - Reporting organic search performance (clicks, impressions, CTR, average position) for a site, a page group, or a query group over a date range, including period-over-period comparisons. - Pulling the full query and page dataset beyond Search Console's 1,000-row export limit (up to 25,000 rows per request). - Separating **branded vs. non-branded** traffic, or grouping queries and pages into saved **segments** and **topic clusters** without regex. - Diagnosing **keyword cannibalization** (several pages ranking for the same query) and finding **growth opportunities** (high-impression, low-CTR queries). - Spotting rising and decaying queries, and checking whether a **Google core update** coincided with a traffic change. - Recording **annotations** for site changes and campaigns so they appear on every chart. - Producing **read-only share links** to live dashboards for clients and stakeholders who have no account. Do **not** use Serql for: keyword volume research outside of GSC (only available through the optional BYOK DataForSEO/Ahrefs integrations), rank tracking of competitors, crawling or auditing a site, Google Analytics data, or paid-search data. Serql is read-only against Google Search Console and never changes Search Console settings. ### How an agent should call Serql 1. Prefer the **MCP server** at `https://www.serql.io/mcp` (Streamable HTTP, OAuth 2.0 via the site's Clerk authorization server). Call `list_properties` first to obtain `propertyId` values, then `get_performance`, `get_cannibalization`, `get_growth_opportunities`, `get_query_insights`, or `list_annotations`. 2. Or call the **REST API** described by the OpenAPI document at `https://www.serql.io/openapi.json` with a Clerk OAuth bearer token (see `https://www.serql.io/auth.md`). 3. For questions about the product itself, use the unauthenticated **documentation MCP server** at `https://www.serql.io/api/mcp/docs` or `POST https://www.serql.io/ask`. 4. Dates are `YYYY-MM-DD`; Search Console data lags two to three days, so end a range at "today minus 3 days" unless the user says otherwise. ## Discovery files - [llms.txt](https://www.serql.io/llms.txt) — navigation index for language models; [llms-full.txt](https://www.serql.io/llms-full.txt) has every document inline. - [index.md](https://www.serql.io/index.md) — this page as markdown. Every public page also has a `.md` twin and answers `Accept: text/markdown`. - [Documentation](https://www.serql.io/docs) — developer docs ([docs/llms.txt](https://www.serql.io/docs/llms.txt)). - [OpenAPI 3.1](https://www.serql.io/openapi.json) — REST API description; [API catalog (RFC 9727)](https://www.serql.io/.well-known/api-catalog); [API llms.txt](https://www.serql.io/api/llms.txt). - [MCP server card](https://www.serql.io/.well-known/mcp/server-card.json) — product MCP server at `https://www.serql.io/mcp`, docs MCP server at `https://www.serql.io/api/mcp/docs`. - [auth.md](https://www.serql.io/auth.md) — how agents obtain credentials; [OAuth protected resource metadata](https://app.serql.io/.well-known/oauth-protected-resource); [authorization server metadata](https://app.serql.io/.well-known/oauth-authorization-server). - [Agent card (A2A)](https://www.serql.io/.well-known/agent-card.json), [Agent skills index](https://www.serql.io/.well-known/agent-skills/index.json), [ARD catalog](https://www.serql.io/.well-known/ard.json), [agent.json](https://www.serql.io/agent.json) (also served at `https://www.serql.io/?mode=agent`). - [pricing.md](https://www.serql.io/pricing.md) — machine-readable pricing. - [Source code](https://github.com/snowopsdev/serql) — AGPL-3.0-only; contains `AGENTS.md`, `plugin.json`, and a `skills/` directory for coding agents. ## Markdown everywhere Every public page can be fetched as markdown three ways: 1. Append `.md` to the path: `https://www.serql.io/index.md`, `https://www.serql.io/about.md`, `https://www.serql.io/docs/api.md`. 2. Send `Accept: text/markdown` to the HTML URL (responses set `Vary: Accept`). 3. Requests from known AI user agents (GPTBot, ClaudeBot, PerplexityBot, and others) receive markdown automatically. Every served markdown document opens with a YAML frontmatter block (`title`, `description`, `canonical`, `last-updated`, `section`) followed by a level-1 heading, and carries `Link: rel="canonical"` and `Last-Modified` headers. HTML pages advertise their twin with `` and an RFC 8288 `Link` header. Nonexistent paths return a real `404` with a short markdown body listing where to look next. ## Agent skill The skill file at https://www.serql.io/skills/serql/SKILL.md (indexed with a SHA-256 digest at https://www.serql.io/.well-known/agent-skills/index.json) tells an agent when to use Serql, how to authenticate, and which tools to call in which order. Install it into a coding agent with `npx skills add snowopsdev/serql`. ## In-page tools (WebMCP) The homepage registers browser-side tools through the proposed [WebMCP](https://github.com/webmachinelearning/webmcp) API (`navigator.modelContext`): `search_docs`, `get_pricing`, and `get_agent_resources`. Browser agents can call them without leaving the page. ## Natural-language questions (NLWeb) `POST https://www.serql.io/ask` with `{ "query": "how do I authenticate?" }` returns NLWeb-shaped JSON (`_meta`, `results[]` with `url`, `name`, `description`, `score`). Send `"streaming": true` (or `?streaming=true`) for a `text/event-stream` response with `start`, `result`, and `complete` events. ## Coding agents The source repository (https://github.com/snowopsdev/serql) contains: - `AGENTS.md` / `CLAUDE.md` — how to work in the codebase. - `plugin.json` (agent-plugins.org) with `skills/` and `mcp.json` — installable as an Agent Plugin. - `skills/serql/SKILL.md` — an Agent Skill describing how to use Serql's API and MCP server (also served at https://www.serql.io/skills/serql/SKILL.md). ## Rate limits and etiquette - Per-user rate limits apply to the API and MCP server; respect `Retry-After`. - `robots.txt` allows answer-engine crawlers and disallows training-only crawlers; `Content-Signal` headers state the same policy. - Do not scrape the authenticated app; use the API or MCP server.