# MCP tools (/reference/mcp-tools)

PeekRank's MCP server has **50 tools**: 20 free, 12 that set things up and 18 billed.
This page is generated from the server's own catalog, so it always lists exactly what the server offers. How to
connect is in [Connect your AI assistant](/ai/connect/); how billed tools are kept in check, in
[Spending limits for assistants](/ai/spending-limits/).

- **Free** tools read what PeekRank already stored. They never bill anything.
- **Set-up** tools change the workspace without billing in the call, but some start things that are billed later
  (tracked keywords are checked every week), so they're only listed where billed tools are.
- **Billed** tools fetch fresh data, paid from the workspace's balance (this month's free data first). They require `max_cost_usd`: the most you agree to spend on that call. If the call could cost more, it's refused and nothing is billed.
- Your assistant only sees the tools your connection allows: a read-only connection sees the free ones; owners and
  admins who allowed it see the workspace-management ones.

## Start here

### get_seo_snapshot

**SEO snapshot.** Start here: every project at a glance — keywords tracked, top 3 / top 10, average position, what moved in the last N days (gains, losses, top-10 entries and exits), the domain's week-over-week traffic and links, Prompt Tracking — plus a short list of what needs attention, the balance and the latest saved runs. Free.

- **Cost:** Free
- **Who:** Any member. Listed for: Every connection, read-only ones included. OAuth scope `peekrank:read`.
- **Hints:** read-only · idempotent
- **In the app:** [Dashboard](/start/navigate/)

| Input | Type | |
|---|---|---|
| `project_id` | `string` | Just this project (default: all, up to 25). Up to 64 characters. |
| `days` | `integer` | Look-back window for the changes (default 7). ≥ 1, ≤ 90. |

Ask your assistant: *“How is my SEO doing this week?”* · *“What needs my attention across my projects?”*

### find

**Find a project, keyword, prompt or run.** Resolves a name to its id: searches project names and domains, tracked keywords, Prompt Tracking prompts and saved runs (research seeds, analysed domains). Every word must match; best matches first. Free.

- **Cost:** Free
- **Who:** Any member. Listed for: Every connection, read-only ones included. OAuth scope `peekrank:read`.
- **Hints:** read-only · idempotent

| Input | Type | |
|---|---|---|
| `query` | `string` | **Required.** What to look for, e.g. "acme", "running shoes". Up to 200 characters. |
| `types` | `("project" \| "keyword" \| "run" \| "prompt")[]` | Only these kinds (default: all). |
| `limit` | `integer` | Default 15. ≥ 1, ≤ 50. |

Ask your assistant: *“Find my keyword 'running shoes'.”* · *“Which project is acme.com?”*

### list_runs

**List saved runs.** Saved keyword research, domain overview, competitor gap, backlink overview, backlink gap, site audit and individual-backlinks runs (newest first), with what they cost. Free.

- **Cost:** Free
- **Who:** Any member. Listed for: Every connection, read-only ones included. OAuth scope `peekrank:read`.
- **Hints:** read-only · idempotent
- **In the app:** [Keyword Research](/seo/keyword-research/), [Domain Overview](/seo/domain-overview/), [Backlink Overview](/seo/backlinks/), [Competitor Gap](/seo/competitor-gap/), [Site Audit](/seo/site-audit/)

| Input | Type | |
|---|---|---|
| `tool` | `"keyword_research" \| "domain_overview" \| "competitor_gap" \| "backlink_overview" \| "backlink_gap" \| "site_audit" \| "backlink_links"` | Only runs of this tool. |
| `limit` | `integer` | Default 20. ≥ 1, ≤ 50. |

Ask your assistant: *“What research did we run last week?”*

### get_run

**Read a saved run.** The full result of a saved run (keyword ideas, a domain's ranking keywords, a competitor gap, a backlink overview's referring domains, a backlink gap's prospects or a list of individual backlinks), paginated. A domain overview's keywords can be filtered like on its page. Re-reading never fetches fresh data — free.

- **Cost:** Free
- **Who:** Any member. Listed for: Every connection, read-only ones included. OAuth scope `peekrank:read`.
- **Hints:** read-only · idempotent
- **In the app:** [Keyword Research](/seo/keyword-research/), [Domain Overview](/seo/domain-overview/), [Backlink Overview](/seo/backlinks/), [Competitor Gap](/seo/competitor-gap/)

| Input | Type | |
|---|---|---|
| `run_id` | `string` | **Required.** From list_runs or a billed tool's result (krr_…, dov_…, gap_…, blr_…, bgap_…, bll_…). Up to 64 characters. |
| `offset` | `integer` | Skip this many rows (pagination). ≥ 0, ≤ 9007199254740991. |
| `limit` | `integer` | Default 50. ≥ 1, ≤ 200. |
| `missing_only` | `boolean` | Competitor gap only: just the keywords you don't rank for. |
| `filters` | `object` | Domain overview only: filter its stored keywords (free; fetch_domain_keywords fetches more that match). |
| `filters.position` | `object` | Google position: &#123;min, max&#125;. |
| `filters.position.min` | `number` |  |
| `filters.position.max` | `number` |  |
| `filters.volume` | `object` | Search volume: &#123;min, max&#125;. |
| `filters.volume.min` | `number` |  |
| `filters.volume.max` | `number` |  |
| `filters.difficulty` | `object` | Difficulty 0–100: &#123;min, max&#125;. |
| `filters.difficulty.min` | `number` |  |
| `filters.difficulty.max` | `number` |  |
| `filters.intent` | `("informational" \| "navigational" \| "commercial" \| "transactional")[]` | Any of these intents. |
| `filters.hosts` | `string[]` | Ranking host is any of these (e.g. blog.acme.com). |
| `filters.url` | `string` | Ranking URL text (see url_mode). Up to 2048 characters. |
| `filters.url_mode` | `"contains" \| "excludes" \| "starts" \| "exact"` | Default contains. |
| `filters.include_words` | `string[]` | Keyword contains any of these. Up to 20 items. |
| `filters.exclude_words` | `string[]` | Keyword contains none of these. Up to 20 items. |
| `filters.serp_features` | `string[]` | SERP shows any of these, e.g. ai_overview, featured_snippet. |
| `filters.result_types` | `string[]` | The domain's result type, e.g. organic. |

Ask your assistant: *“Show all the keyword ideas from my last research.”* · *“Which of rival.com's keywords rank 4–10 with volume over 1,000?”*

### send_feedback

**Send feedback to PeekRank.** Sends a message to the PeekRank team — a bug, a missing feature, an idea. Say what happened in plain words; never include passwords or keys. Nothing is billed.

- **Cost:** Set-up, nothing billed in the call
- **Who:** Any member. Listed for: Connections allowed to run billed tools ("Read + run billed tools" when connecting, or an API key with "Read + billed tools"). OAuth scope `peekrank:run`.
- **Hints:** changes data
- **In the app:** [Dashboard](/start/navigate/)

| Input | Type | |
|---|---|---|
| `message` | `string` | **Required.** 1–2000 characters. Up to 2000 characters. |

Ask your assistant: *“Tell PeekRank the domain overview of my site looks wrong.”*

## Projects

### list_projects

**List projects.** The workspace's projects: id, name, domain, number of tracked keywords and check frequency. Free.

- **Cost:** Free
- **Who:** Any member. Listed for: Every connection, read-only ones included. OAuth scope `peekrank:read`.
- **Hints:** read-only · idempotent
- **In the app:** [Projects](/rank-tracking/projects/)

No inputs.

Ask your assistant: *“List my projects.”*

### get_domain_metrics

**Domain metrics.** A project domain's weekly snapshots (organic keywords, estimated traffic, backlinks, referring domains) and, if it was loaded, its monthly organic history. Free.

- **Cost:** Free
- **Who:** Any member. Listed for: Every connection, read-only ones included. OAuth scope `peekrank:read`.
- **Hints:** read-only · idempotent
- **In the app:** [A project's page](/rank-tracking/project-page/)

| Input | Type | |
|---|---|---|
| `project_id` | `string` | **Required.** A project id (from list_projects, find or get_seo_snapshot). Up to 64 characters. |
| `weeks` | `integer` | Weekly snapshots to return, newest first (default 8). ≥ 1, ≤ 52. |

Ask your assistant: *“How has my domain's traffic changed week by week?”*

### create_project

**Create a project.** Creates a project (a site to track) in this workspace. Nothing is billed. The free plan includes 1 project — more after the first top-up. Then track keywords with add_keywords.

- **Cost:** Set-up, nothing billed in the call
- **Who:** Any member. Listed for: Connections allowed to run billed tools ("Read + run billed tools" when connecting, or an API key with "Read + billed tools"). OAuth scope `peekrank:run`.
- **Hints:** changes data
- **In the app:** [Projects](/rank-tracking/projects/)

| Input | Type | |
|---|---|---|
| `name` | `string` | **Required.** e.g. the client or site name. Up to 120 characters. |
| `domain` | `string` | The site whose positions are tracked, e.g. acme.com. Up to 253 characters. |
| `location` | `string` | Default location of its keywords (default: United States). Up to 120 characters. |
| `device` | `"desktop" \| "mobile"` | Default device (desktop). |

Ask your assistant: *“Create a project for acme.com.”*

### archive_project

**Archive a project.** Archives a project (owners and admins only): its automatic checks stop, it leaves the project list and its public report and audit links are revoked. The data is kept, but there's no self-serve undo — ask the user first.

- **Cost:** Set-up, nothing billed in the call
- **Who:** Owners and admins. Listed for: Connections allowed to run billed tools ("Read + run billed tools" when connecting, or an API key with "Read + billed tools"). OAuth scope `peekrank:run`.
- **Hints:** changes data · destructive · idempotent
- **In the app:** [A project's page](/rank-tracking/project-page/)

| Input | Type | |
|---|---|---|
| `project_id` | `string` | **Required.** A project id (from list_projects, find or get_seo_snapshot). Up to 64 characters. |

Ask your assistant: *“Archive the old test project.”*

### refresh_domain_metrics

**Refresh a project domain's numbers (billed).** Takes this week's snapshot of a project domain now — ranking keywords, top 10, estimated traffic, backlinks, referring domains, authority — instead of waiting for the automatic weekly one. get_domain_metrics and get_seo_snapshot read it for free. Billed from the workspace's PeekRank balance: ≈ $0.072, at most $0.072. Set max_cost_usd ≥ 0.0724.

- **Cost:** Billed: $0.072 per call
- **Who:** Any member. Listed for: Connections allowed to run billed tools ("Read + run billed tools" when connecting, or an API key with "Read + billed tools"). OAuth scope `peekrank:run`.
- **Hints:** changes data · fetches fresh data
- **In the app:** [A project's page](/rank-tracking/project-page/)

| Input | Type | |
|---|---|---|
| `project_id` | `string` | **Required.** A project id (from list_projects, find or get_seo_snapshot). Up to 64 characters. |
| `max_cost_usd` | `number` | **Required.** Most you accept to pay for this call, in USD; if it could cost more it's refused and nothing is billed. &gt; 0, ≤ 100. |

Ask your assistant: *“Refresh my domain's traffic and backlinks numbers now.”*

## Rank tracking

### get_project

**Get project rankings.** A project's tracked keywords with their current Google position, 7-day change, search volume, difficulty, CPC and intent, plus a summary (top 3 / top 10 counts, average position) and its public report link, if any. Collects finished position checks first and copies missing metrics from saved analyses (both free). Paginated. Free.

- **Cost:** Free
- **Who:** Any member. Listed for: Every connection, read-only ones included. OAuth scope `peekrank:read`.
- **Hints:** read-only · idempotent
- **In the app:** [A project's page](/rank-tracking/project-page/)

| Input | Type | |
|---|---|---|
| `project_id` | `string` | **Required.** A project id (from list_projects, find or get_seo_snapshot). Up to 64 characters. |
| `sort` | `"rank" \| "volume" \| "change" \| "keyword"` | rank (default, best first), volume, change (biggest 7-day gain first) or keyword. |
| `offset` | `integer` | Skip this many keywords (pagination). ≥ 0, ≤ 9007199254740991. |
| `limit` | `integer` | Default 50. ≥ 1, ≤ 200. |

Ask your assistant: *“Show the rankings of my Acme project.”* · *“Which of my keywords are in the top 3?”*

### whats_changed

**What changed.** Ranking movements of a project over the last N days: biggest gains and losses, keywords that entered or left the top 10, new and lost rankings. Free.

- **Cost:** Free
- **Who:** Any member. Listed for: Every connection, read-only ones included. OAuth scope `peekrank:read`.
- **Hints:** read-only · idempotent
- **In the app:** [A project's page](/rank-tracking/project-page/)

| Input | Type | |
|---|---|---|
| `project_id` | `string` | **Required.** A project id (from list_projects, find or get_seo_snapshot). Up to 64 characters. |
| `days` | `integer` | Look-back window (default 7). ≥ 1, ≤ 365. |

Ask your assistant: *“Which keywords dropped this week?”* · *“What entered the top 10 this month?”*

### get_keyword_history

**Keyword rank history.** Every recorded position of one tracked keyword over time (date, rank, source), oldest first. Free.

- **Cost:** Free
- **Who:** Any member. Listed for: Every connection, read-only ones included. OAuth scope `peekrank:read`.
- **Hints:** read-only · idempotent
- **In the app:** [A project's page](/rank-tracking/project-page/)

| Input | Type | |
|---|---|---|
| `keyword_id` | `string` | **Required.** A keyword id from get_project. Up to 64 characters. |
| `limit` | `integer` | Newest N points (default 104). ≥ 1, ≤ 500. |

Ask your assistant: *“Show the position history of 'running shoes'.”*

### diagnose_keyword

**Why did this keyword move?.** Explains a tracked keyword's move over the last N days from what PeekRank stored: position then and now, when the biggest jump happened, volatility, an AI Overview appearing or citing you, whether the rest of the project moved the same way (site-wide vs isolated), the domain's traffic and links in the same weeks, and the SERP features competing for clicks. Written findings + next steps. Free.

- **Cost:** Free
- **Who:** Any member. Listed for: Every connection, read-only ones included. OAuth scope `peekrank:read`.
- **Hints:** read-only · idempotent

| Input | Type | |
|---|---|---|
| `keyword_id` | `string` | **Required.** A keyword id (get_project, whats_changed or find). Up to 64 characters. |
| `days` | `integer` | Look-back window (default 30). ≥ 1, ≤ 365. |

Ask your assistant: *“Why did 'running shoes' drop?”*

### add_keywords

**Track keywords.** Adds keywords to a project's rank tracking (already-tracked ones are skipped). Nothing is billed in the call, but every tracked keyword is checked automatically — the first check within about 2 hours, then every 7 days by default — and each check is paid from the workspace's PeekRank balance: ≈ $0.04 per keyword per month at weekly checks. Volume, CPC, KD and intent are copied for free from the workspace's saved analyses. Ask the user before adding many.

- **Cost:** Set-up, nothing billed in the call
- **Who:** Any member. Listed for: Connections allowed to run billed tools ("Read + run billed tools" when connecting, or an API key with "Read + billed tools"). OAuth scope `peekrank:run`.
- **Hints:** changes data · idempotent
- **In the app:** [A project's page](/rank-tracking/project-page/), [Domain Overview](/seo/domain-overview/), [Keyword Research](/seo/keyword-research/), [Competitor Gap](/seo/competitor-gap/)

| Input | Type | |
|---|---|---|
| `project_id` | `string` | **Required.** From list_projects or create_project. Up to 64 characters. |
| `keywords` | `string[]` | **Required.** 1–200 keywords. At least 1 items, up to 200 items. |
| `domain` | `string` | Track another domain than the project's (rare). Up to 253 characters. |
| `location` | `string` | Location (default: the project's). Up to 120 characters. |
| `device` | `"desktop" \| "mobile"` | Device (default: the project's). |

Ask your assistant: *“Track 'running shoes' and 'trail shoes' for acme.com.”*

### remove_keywords

**Stop tracking keywords.** Removes keywords from rank tracking: their automatic checks stop and their position history goes with them (what past checks cost stays in Billing). Ask the user first.

- **Cost:** Set-up, nothing billed in the call
- **Who:** Any member. Listed for: Connections allowed to run billed tools ("Read + run billed tools" when connecting, or an API key with "Read + billed tools"). OAuth scope `peekrank:run`.
- **Hints:** changes data · destructive · idempotent
- **In the app:** [A project's page](/rank-tracking/project-page/)

| Input | Type | |
|---|---|---|
| `keyword_ids` | `string[]` | **Required.** Keyword ids from get_project or find. At least 1 items, up to 100 items. |

Ask your assistant: *“Stop tracking the keywords that have been out of the top 100 for a month.”*

### scan_keyword

**Check a keyword's position now (billed).** A live Google check (top 100) of one tracked keyword, answered in the call; updates its position and history. Weekly checks already run automatically, and check_rankings checks many keywords for less (results within minutes) — use this only when you need one position right now. Billed from the workspace's PeekRank balance: ≈ $0.031, at most $0.031. Set max_cost_usd ≥ 0.0310.

- **Cost:** Billed: $0.031 per keyword
- **Who:** Any member. Listed for: Connections allowed to run billed tools ("Read + run billed tools" when connecting, or an API key with "Read + billed tools"). OAuth scope `peekrank:run`.
- **Hints:** changes data · fetches fresh data
- **In the app:** [A project's page](/rank-tracking/project-page/)

| Input | Type | |
|---|---|---|
| `keyword_id` | `string` | **Required.** A keyword id from get_project. Up to 64 characters. |
| `max_cost_usd` | `number` | **Required.** Most you accept to pay for this call, in USD; if it could cost more it's refused and nothing is billed. &gt; 0, ≤ 100. |

Ask your assistant: *“Where does 'running shoes' rank right now?”*

### check_rankings

**Check tracked keywords now (billed).** Re-checks a project's tracked keywords on Google now (top 100, the automatic weekly check run early); results land within minutes and get_project collects them free. Keywords already being checked are skipped. Billed per keyword from the workspace's PeekRank balance: $0.0093 each — at most $0.465 for 50. Set max_cost_usd ≥ 0.0093 × keywords; a refusal quotes the exact max.

- **Cost:** Billed: $0.0093 per keyword
- **Who:** Any member. Listed for: Connections allowed to run billed tools ("Read + run billed tools" when connecting, or an API key with "Read + billed tools"). OAuth scope `peekrank:run`.
- **Hints:** changes data · fetches fresh data
- **In the app:** [A project's page](/rank-tracking/project-page/)

| Input | Type | |
|---|---|---|
| `project_id` | `string` | **Required.** A project id (from list_projects, find or get_seo_snapshot). Up to 64 characters. |
| `keyword_ids` | `string[]` | Default: every tracked keyword of the project (first 200). At least 1 items, up to 200 items. |
| `max_cost_usd` | `number` | **Required.** Most you accept to pay for this call, in USD; if it could cost more it's refused and nothing is billed. &gt; 0, ≤ 100. |

Ask your assistant: *“Re-check all my Acme keywords now.”*

### fetch_keyword_metrics

**Look up tracked keywords' metrics (billed).** Fills volume, CPC, difficulty and intent for a project's tracked keywords that have none — free from saved analyses first, then billed for the rest (no-data keywords aren't retried for 30 days). Billed from the workspace's PeekRank balance: at most $0.024 for 1 keyword, $0.048 for 100. A refusal quotes the exact max; set max_cost_usd ≥ it.

- **Cost:** Billed: $0.048 per 100 keywords
- **Who:** Any member. Listed for: Connections allowed to run billed tools ("Read + run billed tools" when connecting, or an API key with "Read + billed tools"). OAuth scope `peekrank:run`.
- **Hints:** changes data · fetches fresh data
- **In the app:** [A project's page](/rank-tracking/project-page/)

| Input | Type | |
|---|---|---|
| `project_id` | `string` | **Required.** A project id (from list_projects, find or get_seo_snapshot). Up to 64 characters. |
| `keyword_ids` | `string[]` | Default: every keyword of the project without metrics. At least 1 items, up to 1000 items. |
| `max_cost_usd` | `number` | **Required.** Most you accept to pay for this call, in USD; if it could cost more it's refused and nothing is billed. &gt; 0, ≤ 100. |

Ask your assistant: *“Fill in the missing search volumes of my tracked keywords.”*

### backfill_keyword_history

**Load tracked keywords' past positions (billed).** Loads up to 12 months of past monthly Google positions for a project's tracked keywords (default: those without them yet, up to 25 per call), so get_keyword_history and diagnose_keyword see further back than PeekRank's own checks. Billed per keyword from the workspace's PeekRank balance: ≈ $0.00312 each for 12 months, at most $0.078 for 25; within this connection's limits. The refusal message quotes the exact max for your keywords; set max_cost_usd ≥ it.

- **Cost:** Billed: $0.00312 per keyword (12 months)
- **Who:** Any member. Listed for: Connections allowed to run billed tools ("Read + run billed tools" when connecting, or an API key with "Read + billed tools"). OAuth scope `peekrank:run`.
- **Hints:** changes data · fetches fresh data
- **In the app:** [A project's page](/rank-tracking/project-page/)

| Input | Type | |
|---|---|---|
| `project_id` | `string` | **Required.** A project id (from list_projects, find or get_seo_snapshot). Up to 64 characters. |
| `keyword_ids` | `string[]` | Default: the project's keywords without past positions (first 25). At least 1 items, up to 25 items. |
| `months` | `integer` | 1–12 (default 12). ≥ 1, ≤ 12. |
| `max_cost_usd` | `number` | **Required.** Most you accept to pay for this call, in USD; if it could cost more it's refused and nothing is billed. &gt; 0, ≤ 100. |

Ask your assistant: *“Load the last year of positions for my new keywords.”*

## Keyword research

### keyword_research

**Keyword research (billed).** Up to 200 keyword ideas for a seed keyword (search volume, difficulty, CPC, intent), the seed's own metrics and its top-10 Google results. The run is saved: page through all ideas later with get_run for free. Billed from the workspace's PeekRank balance: ≈ $0.10, at most $0.10. Set max_cost_usd ≥ 0.1003.

- **Cost:** Billed: $0.10 per call
- **Who:** Any member. Listed for: Connections allowed to run billed tools ("Read + run billed tools" when connecting, or an API key with "Read + billed tools"). OAuth scope `peekrank:run`.
- **Hints:** changes data · fetches fresh data
- **In the app:** [Keyword Research](/seo/keyword-research/)

| Input | Type | |
|---|---|---|
| `seed` | `string` | **Required.** The seed keyword. Up to 80 characters. |
| `location_code` | `integer` | Location code (Google Ads geo target ID; default 2840 = United States). &gt; 0, ≤ 9007199254740991. |
| `language_code` | `string` | Language, e.g. en (default), es, pt-BR. Up to 8 characters. |
| `engine` | `"google" \| "bing"` | Search engine (default google). |
| `project_id` | `string` | File the run under this project (from list_projects). Up to 64 characters. |
| `max_cost_usd` | `number` | **Required.** Most you accept to pay for this call, in USD; if it could cost more it's refused and nothing is billed. &gt; 0, ≤ 100. |

Ask your assistant: *“Find keyword ideas around 'trail running shoes'.”*

### keyword_lookup

**One keyword's metrics and top 10 (billed).** One keyword's volume, difficulty, CPC, intent and Google top 10, no ideas (keyword_research has them); serp_only = just the top 10. Not saved. Billed from the workspace's PeekRank balance: ≈ $0.028, at most $0.028. Set max_cost_usd ≥ 0.0283. serp_only: at most $0.004.

- **Cost:** Billed: $0.028 per call
- **Who:** Any member. Listed for: Connections allowed to run billed tools ("Read + run billed tools" when connecting, or an API key with "Read + billed tools"). OAuth scope `peekrank:run`.
- **Hints:** changes data · fetches fresh data
- **In the app:** [Keyword Research](/seo/keyword-research/), [Competitor Gap](/seo/competitor-gap/)

| Input | Type | |
|---|---|---|
| `keyword` | `string` | **Required.** The keyword. Up to 80 characters. |
| `serp_only` | `boolean` | Only the Google top 10 (cheaper). |
| `location_code` | `integer` | Location code (Google Ads geo target ID; default 2840 = United States). &gt; 0, ≤ 9007199254740991. |
| `language_code` | `string` | Language, e.g. en (default), es, pt-BR. Up to 8 characters. |
| `engine` | `"google" \| "bing"` | Search engine (default google). |
| `project_id` | `string` | File the run under this project (from list_projects). Up to 64 characters. |
| `max_cost_usd` | `number` | **Required.** Most you accept to pay for this call, in USD; if it could cost more it's refused and nothing is billed. &gt; 0, ≤ 100. |

Ask your assistant: *“What's the volume and difficulty of 'barefoot shoes', and who ranks for it?”*

### load_ai_demand

**AI demand of a keyword research (billed).** Adds AI search demand (how often people ask AI about each keyword — a proxy, not ChatGPT's own numbers) to a saved keyword research run; get_run re-reads it free. Billed from the workspace's PeekRank balance: ≈ $0.06, at most $0.06. Set max_cost_usd ≥ 0.0602.

- **Cost:** Billed: $0.06 per run (≤ 201 keywords)
- **Who:** Any member. Listed for: Connections allowed to run billed tools ("Read + run billed tools" when connecting, or an API key with "Read + billed tools"). OAuth scope `peekrank:run`.
- **Hints:** changes data · fetches fresh data
- **In the app:** [Keyword Research](/seo/keyword-research/)

| Input | Type | |
|---|---|---|
| `run_id` | `string` | **Required.** A keyword research run (krr_…) from keyword_research or list_runs. Up to 64 characters. |
| `max_cost_usd` | `number` | **Required.** Most you accept to pay for this call, in USD; if it could cost more it's refused and nothing is billed. &gt; 0, ≤ 100. |

Ask your assistant: *“Which of these keyword ideas do people also ask AI about?”*

## Domain overview

### domain_overview

**Domain overview (billed).** Any domain's (or page's) organic footprint: total ranking keywords, estimated traffic, position distribution, authority (0–100), its top keywords and top pages. Saved: get_run pages through its 100 keywords for free. Billed from the workspace's PeekRank balance: ≈ $0.096, at most $0.096. Set max_cost_usd ≥ 0.0961.

- **Cost:** Billed: $0.096 per call
- **Who:** Any member. Listed for: Connections allowed to run billed tools ("Read + run billed tools" when connecting, or an API key with "Read + billed tools"). OAuth scope `peekrank:run`.
- **Hints:** changes data · fetches fresh data
- **In the app:** [Domain Overview](/seo/domain-overview/)

| Input | Type | |
|---|---|---|
| `domain` | `string` | **Required.** A domain (example.com) or, with scope=url, a full page URL. Up to 2048 characters. |
| `scope` | `"domain" \| "url"` | domain (default) or url (one page). |
| `project_id` | `string` | File the run under this project (from list_projects). Up to 64 characters. |
| `max_cost_usd` | `number` | **Required.** Most you accept to pay for this call, in USD; if it could cost more it's refused and nothing is billed. &gt; 0, ≤ 100. |

Ask your assistant: *“How much organic traffic does rival.com get, and from which keywords?”*

### fetch_domain_keywords

**Fetch more keywords of a domain overview (billed).** A domain overview stores the domain's 100 best positions; this fetches up to 100 more of its keywords matching filters (highest volume first; call again for the next 100) into the run, so get_run with the same filters reads them free. Try get_run with filters first. Billed from the workspace's PeekRank balance: ≈ $0.048, at most $0.048. Set max_cost_usd ≥ 0.0480.

- **Cost:** Billed: $0.048 per 100 keywords
- **Who:** Any member. Listed for: Connections allowed to run billed tools ("Read + run billed tools" when connecting, or an API key with "Read + billed tools"). OAuth scope `peekrank:run`.
- **Hints:** changes data · fetches fresh data
- **In the app:** [Domain Overview](/seo/domain-overview/)

| Input | Type | |
|---|---|---|
| `run_id` | `string` | **Required.** A domain overview run (dov_…). Up to 64 characters. |
| `filters` | `object` | **Required.** The Domain overview page's keyword filters. |
| `filters.position` | `object` | Google position: &#123;min, max&#125;. |
| `filters.position.min` | `number` |  |
| `filters.position.max` | `number` |  |
| `filters.volume` | `object` | Search volume: &#123;min, max&#125;. |
| `filters.volume.min` | `number` |  |
| `filters.volume.max` | `number` |  |
| `filters.difficulty` | `object` | Difficulty 0–100: &#123;min, max&#125;. |
| `filters.difficulty.min` | `number` |  |
| `filters.difficulty.max` | `number` |  |
| `filters.intent` | `("informational" \| "navigational" \| "commercial" \| "transactional")[]` | Any of these intents. |
| `filters.hosts` | `string[]` | Ranking host is any of these (e.g. blog.acme.com). |
| `filters.url` | `string` | Ranking URL text (see url_mode). Up to 2048 characters. |
| `filters.url_mode` | `"contains" \| "excludes" \| "starts" \| "exact"` | Default contains. |
| `filters.include_words` | `string[]` | Keyword contains any of these. Up to 20 items. |
| `filters.exclude_words` | `string[]` | Keyword contains none of these. Up to 20 items. |
| `filters.serp_features` | `string[]` | SERP shows any of these, e.g. ai_overview, featured_snippet. |
| `filters.result_types` | `string[]` | The domain's result type, e.g. organic. |
| `max_cost_usd` | `number` | **Required.** Most you accept to pay for this call, in USD; if it could cost more it's refused and nothing is billed. &gt; 0, ≤ 100. |

Ask your assistant: *“Get rival.com's keywords ranking 11–30 with volume over 500.”*

### load_domain_history

**Load a domain's monthly history (billed).** A domain's organic footprint month by month — keywords in the top 3 / top 10 / top 50 and estimated traffic — for the last N months (default 24, up to 60): a project's domain (project_id; get_domain_metrics re-reads it free) or a saved domain overview's (run_id; get_run re-reads it free). Billed from the workspace's PeekRank balance: ≈ $0.30, at most $0.30. Set max_cost_usd ≥ 0.3000. (for 24 months; fewer months cost slightly less)

- **Cost:** Billed: $0.30 per 24 months
- **Who:** Any member. Listed for: Connections allowed to run billed tools ("Read + run billed tools" when connecting, or an API key with "Read + billed tools"). OAuth scope `peekrank:run`.
- **Hints:** changes data · fetches fresh data
- **In the app:** [A project's page](/rank-tracking/project-page/), [Domain Overview](/seo/domain-overview/)

| Input | Type | |
|---|---|---|
| `project_id` | `string` | A project (its domain). Pass this or run_id. Up to 64 characters. |
| `run_id` | `string` | A domain overview run (dov_…). Pass this or project_id. Up to 64 characters. |
| `months` | `integer` | 1–60 (default 24). ≥ 1, ≤ 60. |
| `max_cost_usd` | `number` | **Required.** Most you accept to pay for this call, in USD; if it could cost more it's refused and nothing is billed. &gt; 0, ≤ 100. |

Ask your assistant: *“How has acme.com's organic traffic evolved over two years?”*

## Backlinks

### backlink_overview

**Backlink overview (billed).** Any domain's backlink profile: total backlinks, referring domains, authority (0–100), its top referring domains (authority, backlinks, first seen) and anchor-text distribution. Saved: get_run pages through its 100 referring domains for free; load_backlinks lists the individual links. Billed from the workspace's PeekRank balance: ≈ $0.152, at most $0.152. Set max_cost_usd ≥ 0.1520.

- **Cost:** Billed: $0.152 per call
- **Who:** Any member. Listed for: Connections allowed to run billed tools ("Read + run billed tools" when connecting, or an API key with "Read + billed tools"). OAuth scope `peekrank:run`.
- **Hints:** changes data · fetches fresh data
- **In the app:** [Backlink Overview](/seo/backlinks/)

| Input | Type | |
|---|---|---|
| `domain` | `string` | **Required.** A domain (example.com). Up to 2048 characters. |
| `include_subdomains` | `boolean` | Count links to its subdomains too (default true). |
| `project_id` | `string` | File the run under this project (from list_projects). Up to 64 characters. |
| `max_cost_usd` | `number` | **Required.** Most you accept to pay for this call, in USD; if it could cost more it's refused and nothing is billed. &gt; 0, ≤ 100. |

Ask your assistant: *“How many backlinks and referring domains does rival.com have?”*

### load_backlinks

**Individual backlinks of a domain (billed).** A domain's individual backlinks — referring page, its domain's authority, anchor, dofollow, first/last seen — 200 per call, strongest first (up to 1000); pass set_id for the next page. get_run (bll_…) re-reads them free. Billed from the workspace's PeekRank balance: ≈ $0.062, at most $0.062. Set max_cost_usd ≥ 0.0624.

- **Cost:** Billed: $0.062 per 200 links
- **Who:** Any member. Listed for: Connections allowed to run billed tools ("Read + run billed tools" when connecting, or an API key with "Read + billed tools"). OAuth scope `peekrank:run`.
- **Hints:** changes data · fetches fresh data
- **In the app:** [Backlink Overview](/seo/backlinks/)

| Input | Type | |
|---|---|---|
| `domain` | `string` | **Required.** A domain (example.com). Up to 2048 characters. |
| `include_subdomains` | `boolean` | Links to its subdomains too (default true). |
| `mode` | `"as_is" \| "one_per_domain"` | as_is (default) or one_per_domain. |
| `status` | `"live" \| "lost" \| "all"` | live (default), lost or all. |
| `set_id` | `string` | bll_… of an earlier call: its next page (its own options win). Up to 64 characters. |
| `project_id` | `string` | File the run under this project (from list_projects). Up to 64 characters. |
| `max_cost_usd` | `number` | **Required.** Most you accept to pay for this call, in USD; if it could cost more it's refused and nothing is billed. &gt; 0, ≤ 100. |

Ask your assistant: *“List rival.com's dofollow backlinks from the strongest sites.”*

### backlink_gap

**Backlink gap (billed).** Link-building prospects: the domains that link to 1–5 competitors but not to you, each with its authority (0–100) and how many backlinks it gives each rival, the ones linking to the most rivals first (view=referring_domains, default) — or the individual pages linking to them (view=individual_links). Saved: get_run pages through them for free. Billed from the workspace's PeekRank balance: ≈ $0.055, at most $0.055. Set max_cost_usd ≥ 0.0552. (individual_links: ≈ $0.055, at most $0.055)

- **Cost:** Billed: $0.055 per call
- **Who:** Any member. Listed for: Connections allowed to run billed tools ("Read + run billed tools" when connecting, or an API key with "Read + billed tools"). OAuth scope `peekrank:run`.
- **Hints:** changes data · fetches fresh data
- **In the app:** [Competitor Gap](/seo/competitor-gap/)

| Input | Type | |
|---|---|---|
| `domain` | `string` | **Required.** Your domain. Up to 2048 characters. |
| `competitors` | `string[]` | **Required.** 1–5 competitor domains. At least 1 items, up to 5 items. |
| `view` | `"referring_domains" \| "individual_links"` | referring_domains (default) or individual_links. |
| `project_id` | `string` | File the run under this project (from list_projects). Up to 64 characters. |
| `max_cost_usd` | `number` | **Required.** Most you accept to pay for this call, in USD; if it could cost more it's refused and nothing is billed. &gt; 0, ≤ 100. |

Ask your assistant: *“Which sites link to my competitors but not to me?”*

## Competitor gap

### competitor_gap

**Competitor gap (billed).** The keywords 1–5 competitors rank for, with your position next to each (null = you don't rank). Saved: get_run with missing_only=true lists every keyword you're missing, free. Billed per domain (you + each competitor) from the workspace's PeekRank balance: ≈ $0.072 each, at most $0.072 each — e.g. with 3 competitors at most $0.288; within this connection's limits. Set max_cost_usd ≥ the max for your number of competitors.

- **Cost:** Billed: $0.072 per domain (you + each competitor)
- **Who:** Any member. Listed for: Connections allowed to run billed tools ("Read + run billed tools" when connecting, or an API key with "Read + billed tools"). OAuth scope `peekrank:run`.
- **Hints:** changes data · fetches fresh data
- **In the app:** [Competitor Gap](/seo/competitor-gap/)

| Input | Type | |
|---|---|---|
| `domain` | `string` | **Required.** Your domain. Up to 2048 characters. |
| `competitors` | `string[]` | **Required.** 1–5 competitor domains. At least 1 items, up to 5 items. |
| `project_id` | `string` | File the run under this project (from list_projects). Up to 64 characters. |
| `max_cost_usd` | `number` | **Required.** Most you accept to pay for this call, in USD; if it could cost more it's refused and nothing is billed. &gt; 0, ≤ 100. |

Ask your assistant: *“Which keywords do rival.com and other.com rank for that I don't?”*

## Site audit

### get_site_audit

**Site audit result.** A site audit's state: while crawling, its progress; when done, the health score (0–100), pages crawled and the issues found (worst first, with how many pages have each), plus its public share link if any. With issue, the pages that have that issue. wait_seconds waits on PeekRank's side (up to 50 s) for a running crawl to finish. Free.

- **Cost:** Free
- **Who:** Any member. Listed for: Every connection, read-only ones included. OAuth scope `peekrank:read`.
- **Hints:** read-only · idempotent
- **In the app:** [A site audit](/seo/site-audit/)

| Input | Type | |
|---|---|---|
| `audit_id` | `string` | **Required.** From start_site_audit, list_runs or find (aud_…). Up to 64 characters. |
| `wait_seconds` | `integer` | Wait for a running crawl, up to 50 s (default 0). ≥ 0, ≤ 50. |
| `issue` | `string` | An issue key from this audit's issues (e.g. no_title): list the pages that have it. Up to 64 characters. |

Ask your assistant: *“Is my site audit done? What are the worst issues?”* · *“Which pages are missing a title?”*

### start_site_audit

**Start a site audit (billed).** Crawls a site (up to max_pages pages, default 100) and checks it for technical SEO issues — broken pages and links, redirect loops, missing or duplicate titles, descriptions and H1s, duplicate or thin content, images without alt text… The crawl runs in the background for a few minutes: read it with get_site_audit (free). Billed per page of max_pages, up front, from the workspace's PeekRank balance: $0.03 for 100 pages, at most $0.15 (500 pages); within this connection's limits. Set max_cost_usd ≥ the price for your max_pages.

- **Cost:** Billed: $0.03 per 100 pages
- **Who:** Any member. Listed for: Connections allowed to run billed tools ("Read + run billed tools" when connecting, or an API key with "Read + billed tools"). OAuth scope `peekrank:run`.
- **Hints:** changes data · fetches fresh data
- **In the app:** [Site Audit](/seo/site-audit/)

| Input | Type | |
|---|---|---|
| `domain` | `string` | **Required.** The site to crawl, e.g. acme.com. Up to 2048 characters. |
| `max_pages` | `integer` | 1–500 (default 100). ≥ 1, ≤ 500. |
| `project_id` | `string` | File the run under this project (from list_projects). Up to 64 characters. |
| `max_cost_usd` | `number` | **Required.** Most you accept to pay for this call, in USD; if it could cost more it's refused and nothing is billed. &gt; 0, ≤ 100. |

Ask your assistant: *“Audit acme.com for technical SEO issues.”*

## AI visibility

### get_ai_visibility

**AI visibility (Prompt Tracking).** For a project: whether ChatGPT, Gemini, Google AI Mode and Perplexity name its brand when asked its tracked prompts — per prompt and engine the latest position (place among the brands the answer names, 1 = first), whether it cites the brand's site, and how often in 4 weeks; per-engine totals, share of voice vs tracked competitors, other brands named, and the Prompt Tracking setup. Collects finished checks first. Free.

- **Cost:** Free
- **Who:** Any member. Listed for: Every connection, read-only ones included. OAuth scope `peekrank:read`.
- **Hints:** read-only · idempotent
- **In the app:** [Prompt Tracking](/ai-visibility/prompt-tracking/), [Share of Voice](/ai-visibility/share-of-voice/)

| Input | Type | |
|---|---|---|
| `project_id` | `string` | **Required.** A project id (from list_projects, find or get_seo_snapshot). Up to 64 characters. |

Ask your assistant: *“Does ChatGPT recommend my brand?”* · *“What's my share of voice in AI answers vs my competitors?”*

### get_ai_answer

**Read one AI answer.** The full stored answer of one engine to one prompt (text, brands named in order, cited sources, what it searched for). Free.

- **Cost:** Free
- **Who:** Any member. Listed for: Every connection, read-only ones included. OAuth scope `peekrank:read`.
- **Hints:** read-only · idempotent
- **In the app:** [Prompt Tracking](/ai-visibility/prompt-tracking/)

| Input | Type | |
|---|---|---|
| `project_id` | `string` | **Required.** A project id (from list_projects, find or get_seo_snapshot). Up to 64 characters. |
| `answer_id` | `string` | **Required.** An answer_id from get_ai_visibility. Up to 64 characters. |

Ask your assistant: *“What exactly did Perplexity answer for 'best running shoe shop'?”*

### get_ai_sources

**Sites AI answers cite.** The sites the engines cited in a project's AI answers over 30 days — how often, by which engines, top pages — the third-party sites cited where the brand isn't named (worth being on), and its saved topic lookups (ai_topic_sources). Free.

- **Cost:** Free
- **Who:** Any member. Listed for: Every connection, read-only ones included. OAuth scope `peekrank:read`.
- **Hints:** read-only · idempotent
- **In the app:** [AI Sources](/ai-visibility/ai-sources/)

| Input | Type | |
|---|---|---|
| `project_id` | `string` | **Required.** A project id (from list_projects, find or get_seo_snapshot). Up to 64 characters. |
| `limit` | `integer` | Sites to return (default 25). ≥ 1, ≤ 100. |

Ask your assistant: *“Which sites do AI answers cite in my space?”*

### get_ai_overviews

**Google AI Overviews on tracked keywords.** For a project's tracked keywords, from their last rank check: whether Google showed an AI Overview, whether it cites the project's domain (and at which position among its sources), and the most cited domains. Free.

- **Cost:** Free
- **Who:** Any member. Listed for: Every connection, read-only ones included. OAuth scope `peekrank:read`.
- **Hints:** read-only · idempotent
- **In the app:** [AI Overviews](/ai-visibility/ai-overviews/)

| Input | Type | |
|---|---|---|
| `project_id` | `string` | **Required.** A project id (from list_projects, find or get_seo_snapshot). Up to 64 characters. |
| `limit` | `integer` | Keywords to return (default 50). ≥ 1, ≤ 200. |

Ask your assistant: *“For which keywords does Google's AI Overview cite me?”*

### set_up_prompt_tracking

**Set up Prompt Tracking.** Sets up or changes a project's Prompt Tracking — brand and competitors, engines, weekly or daily, market — and adds prompts (questions a customer would ask an AI). Fields left out keep their value. Nothing is billed in the call, but each prompt is then asked automatically on each engine, paid from the workspace's PeekRank balance: ≈ $0.0024 per prompt per check on ChatGPT, Gemini or AI Mode, ≈ $0.012 on Perplexity, ≈ $0.05 on Claude. Ask the user before adding many prompts or going daily.

- **Cost:** Set-up, nothing billed in the call
- **Who:** Any member. Listed for: Connections allowed to run billed tools ("Read + run billed tools" when connecting, or an API key with "Read + billed tools"). OAuth scope `peekrank:run`.
- **Hints:** changes data · idempotent
- **In the app:** [Prompt Tracking](/ai-visibility/prompt-tracking/)

| Input | Type | |
|---|---|---|
| `project_id` | `string` | **Required.** A project id (from list_projects, find or get_seo_snapshot). Up to 64 characters. |
| `brand` | `object` | The project's brand (the first time, default: the project's name and domain). |
| `brand.name` | `string` | **Required.** e.g. Acme. Up to 120 characters. |
| `brand.aliases` | `string[]` | Other spellings, product names. Up to 10 items. |
| `brand.domains` | `string[]` | Its sites, e.g. acme.com. Up to 5 items. |
| `competitors` | `object[]` | Competitors for share of voice (replaces the list). Up to 10 items. |
| `competitors[].name` | `string` | **Required.** e.g. Acme. Up to 120 characters. |
| `competitors[].aliases` | `string[]` | Other spellings, product names. Up to 10 items. |
| `competitors[].domains` | `string[]` | Its sites, e.g. acme.com. Up to 5 items. |
| `engines` | `("chatgpt" \| "gemini" \| "google_ai_mode" \| "perplexity" \| "claude")[]` | Default first time: all but claude (it costs more). At least 1 items, up to 5 items. |
| `cadence_days` | `7 \| 1` | 7 = weekly (default), 1 = daily. |
| `market` | `string` | location:language, e.g. "2840:en" (default) or "2724:es". Up to 16 characters. |
| `add_prompts` | `string[]` | Prompts to start tracking. Up to 50 items. |

Ask your assistant: *“Track whether ChatGPT and Perplexity recommend Acme against Rival for 'best running shoe shop'.”*

### archive_prompts

**Stop tracking prompts.** Stops tracking Prompt Tracking prompts: they're no longer asked. Their answers and what they cost stay. Ask the user first.

- **Cost:** Set-up, nothing billed in the call
- **Who:** Any member. Listed for: Connections allowed to run billed tools ("Read + run billed tools" when connecting, or an API key with "Read + billed tools"). OAuth scope `peekrank:run`.
- **Hints:** changes data · destructive · idempotent
- **In the app:** [Prompt Tracking](/ai-visibility/prompt-tracking/)

| Input | Type | |
|---|---|---|
| `project_id` | `string` | **Required.** A project id (from list_projects, find or get_seo_snapshot). Up to 64 characters. |
| `prompt_ids` | `string[]` | **Required.** Prompt ids from get_ai_visibility or find. At least 1 items, up to 200 items. |

Ask your assistant: *“Stop tracking the prompt about free shipping.”*

### check_ai_prompts

**Ask the AI engines again (billed).** Asks a project's Prompt Tracking prompts again on its engines (default: all its prompts, at most 10 per call; add_prompts tracks new ones first). Perplexity (and Claude) answer within the call; ChatGPT, Gemini and Google AI Mode within minutes — read them later with get_ai_visibility (free). Billed per prompt and engine from the workspace's PeekRank balance: ≈ $0.0024 per interface engine (ChatGPT, Gemini, AI Mode) and ≈ $0.012 (at most $0.03) for Perplexity — with those four, at most $0.037 per prompt; Claude, when a project turned it on, ≈ $0.05 (at most $0.10); within this connection's limits. Set max_cost_usd ≥ 0.0372 × prompts (those four engines); a refusal quotes the exact max.

- **Cost:** Billed: ≈ $0.019 per prompt (4 engines) (at most $0.037)
- **Who:** Any member. Listed for: Connections allowed to run billed tools ("Read + run billed tools" when connecting, or an API key with "Read + billed tools"). OAuth scope `peekrank:run`.
- **Hints:** changes data · fetches fresh data
- **In the app:** [Prompt Tracking](/ai-visibility/prompt-tracking/)

| Input | Type | |
|---|---|---|
| `project_id` | `string` | **Required.** A project id (from list_projects, find or get_seo_snapshot). Up to 64 characters. |
| `prompt_ids` | `string[]` | From get_ai_visibility; default = the project's prompts (first 10). At least 1 items, up to 10 items. |
| `add_prompts` | `string[]` | New prompts to track (and ask) first — natural questions a customer would ask an AI. Up to 5 items. |
| `max_cost_usd` | `number` | **Required.** Most you accept to pay for this call, in USD; if it could cost more it's refused and nothing is billed. &gt; 0, ≤ 100. |

Ask your assistant: *“Ask ChatGPT and Perplexity my prompts again now.”*

### ai_topic_sources

**Sites and brands AI cites for a topic (billed).** For a short topic (e.g. "rank tracker", not a question): the sites AI answers cite most and, on ChatGPT, the brands they name most, in the project's Prompt Tracking market (ChatGPT: US English only). get_ai_sources re-reads it free. Billed from the workspace's PeekRank balance: ≈ $0.24, at most $0.24. Set max_cost_usd ≥ 0.2400.

- **Cost:** Billed: $0.24 per call
- **Who:** Any member. Listed for: Connections allowed to run billed tools ("Read + run billed tools" when connecting, or an API key with "Read + billed tools"). OAuth scope `peekrank:run`.
- **Hints:** changes data · fetches fresh data
- **In the app:** [AI Sources](/ai-visibility/ai-sources/)

| Input | Type | |
|---|---|---|
| `project_id` | `string` | **Required.** A project id (from list_projects, find or get_seo_snapshot). Up to 64 characters. |
| `topic` | `string` | **Required.** A short topic, e.g. "rank tracker". Up to 80 characters. |
| `platform` | `"google" \| "chat_gpt"` | google = Google's AI Overviews (default), chat_gpt = ChatGPT (US English only). |
| `max_cost_usd` | `number` | **Required.** Most you accept to pay for this call, in USD; if it could cost more it's refused and nothing is billed. &gt; 0, ≤ 100. |

Ask your assistant: *“Which sites does AI cite most about 'running shoes'?”*

## Reports & sharing

### share_link

**Public share link.** Creates (or returns) the public link to a project's ranking report or a site audit — anyone with it can open it, with the workspace's report branding; optionally expiring in 7, 30 or 90 days — or rotates (the old link dies) or revokes it. Ask the user first: it publishes the data.

- **Cost:** Set-up, nothing billed in the call
- **Who:** Owners and admins. Listed for: Owners and admins who ticked "Also manage the workspace" when connecting their AI app (never API keys). OAuth scope `peekrank:manage`.
- **Hints:** changes data · destructive · fetches fresh data
- **In the app:** [A project's page](/rank-tracking/project-page/), [A site audit](/seo/site-audit/)

| Input | Type | |
|---|---|---|
| `action` | `"create" \| "rotate" \| "revoke"` | **Required.** create (or return the active link), rotate or revoke. |
| `project_id` | `string` | A project's ranking report. Pass this or audit_id. Up to 64 characters. |
| `audit_id` | `string` | A site audit (aud_…). Pass this or project_id. Up to 64 characters. |
| `expires_in_days` | `7 \| 30 \| 90 \| null` | New links only: 7, 30 or 90; null or left out = never. |

Ask your assistant: *“Give me a link to share Acme's rankings with the client for 30 days.”*

### set_report_branding

**Report branding.** The white-label look of every public report and audit link: name, primary and secondary colours (#rrggbb), hiding PeekRank's mark, and the logo (a PNG, JPEG or WebP data: URL, never SVG) or removing it. Fields left out stay as they are.

- **Cost:** Set-up, nothing billed in the call
- **Who:** Owners and admins. Listed for: Owners and admins who ticked "Also manage the workspace" when connecting their AI app (never API keys). OAuth scope `peekrank:manage`.
- **Hints:** changes data · idempotent
- **In the app:** [Settings → Workspace](/reports/white-label/)

| Input | Type | |
|---|---|---|
| `brand_name` | `string \| null` | Shown on the reports, e.g. "Acme Agency"; null = none. |
| `primary_color` | `string \| null` | #rrggbb; null = PeekRank's. |
| `secondary_color` | `string \| null` | #rrggbb for the header band; null = none. |
| `hide_branding` | `boolean` | Hide the small PeekRank mark. |
| `logo_data_url` | `string` | data:image/png;base64,… (PNG, JPEG or WebP, ≤ 170 KB through an assistant, ≤ 4000 px; bigger files: upload in PeekRank → Settings → Workspace). Up to 240000 characters. |
| `remove_logo` | `boolean` | Remove the logo. |

Ask your assistant: *“Brand our client reports as 'Acme Agency' in #0a7cff.”*

## Team

### get_workspace

**Workspace, plan and team.** This workspace: your role and projects, its plan (free data per month, lifetime deal), report branding, members (role, projects) and pending invites. Free.

- **Cost:** Free
- **Who:** Any member. Listed for: Every connection, read-only ones included. OAuth scope `peekrank:read`.
- **Hints:** read-only · idempotent
- **In the app:** [Team](/team/members/), [Settings → Workspace](/reports/white-label/)

No inputs.

Ask your assistant: *“Who is on my team and what can they see?”* · *“What plan is this workspace on?”*

### manage_team

**Manage the team.** Invite someone as a member (an email to join; optionally only some projects), change which projects a member sees, make an admin a member, remove someone or revoke an invite. Never makes anyone an admin or touches the owner (that's PeekRank → Team). Ask the user before each change: people gain or lose access to the data.

- **Cost:** Set-up, nothing billed in the call
- **Who:** Owners and admins. Listed for: Owners and admins who ticked "Also manage the workspace" when connecting their AI app (never API keys). OAuth scope `peekrank:manage`.
- **Hints:** changes data · destructive · fetches fresh data
- **In the app:** [Team](/team/members/)

| Input | Type | |
|---|---|---|
| `action` | `"invite" \| "set_projects" \| "make_member" \| "remove" \| "revoke_invite"` | **Required.** What to do. |
| `email` | `string` | invite: who to invite. Up to 254 characters. |
| `member_id` | `string` | set_projects / make_member / remove: a member's user_id from get_workspace. Up to 64 characters. |
| `invite_id` | `string` | revoke_invite: an invite id from get_workspace. Up to 64 characters. |
| `project_ids` | `string[] \| null` | invite / set_projects: only these projects (at least one); null = all projects (invite: left out = all too). |

Ask your assistant: *“Invite ana@acme.com to see only the Acme project.”* · *“Remove Mia from the workspace.”*

## Balance & billing

### get_budget

**Budget and limits.** The workspace's balance (this month's free data, then what it topped up), and this connection's (or API key's) MCP access, per-call and daily limits and what it spent today. Free.

- **Cost:** Free
- **Who:** Any member. Listed for: Every connection, read-only ones included. OAuth scope `peekrank:read`.
- **Hints:** read-only · idempotent
- **In the app:** [Data &amp; billing](/billing/balance/)

No inputs.

Ask your assistant: *“How much balance do I have left?”*

### get_spending

**Spending report.** What the workspace spent from its balance in 7, 30 or 90 days: total vs the period before, by tool, project, person, day and connection (app vs AI assistants), and the priciest calls. Free.

- **Cost:** Free
- **Who:** Owners and admins. Listed for: Owners and admins, on any connection. OAuth scope `peekrank:read`.
- **Hints:** read-only · idempotent
- **In the app:** [Data &amp; billing](/billing/balance/)

| Input | Type | |
|---|---|---|
| `period` | `7 \| 30 \| 90` | Days (default 30). |

Ask your assistant: *“What did we spend on PeekRank this month, and on what?”*

### create_top_up_link

**Top-up payment link.** Returns a secure payment page to top up the workspace's balance; the person opens it and pays by card, and the balance goes up once paid. This call charges nothing.

- **Cost:** Set-up, nothing billed in the call
- **Who:** Owners and admins. Listed for: Connections allowed to run billed tools ("Read + run billed tools" when connecting, or an API key with "Read + billed tools"). OAuth scope `peekrank:run`.
- **Hints:** changes data · fetches fresh data
- **In the app:** [Data &amp; billing](/billing/balance/)

| Input | Type | |
|---|---|---|
| `amount_usd` | `number` | **Required.** $5–$500. ≥ 5, ≤ 500. |

Ask your assistant: *“My balance is out — give me a link to top up $25.”*

## Connections & security

### list_connections

**Connected apps and API keys.** Connected AI apps (yours; owners and admins see all) with access, last use and today's spend; for owners and admins also API keys and the connection limits. Never a secret. Free.

- **Cost:** Free
- **Who:** Any member. Listed for: Every connection, read-only ones included. OAuth scope `peekrank:read`.
- **Hints:** read-only · idempotent
- **In the app:** [Settings → Developers &amp; AI](/ai/access/)

No inputs.

Ask your assistant: *“Which AI apps are connected to PeekRank?”*

### get_security_log

**Security log.** The workspace's security log, newest first: invites, roles, API keys, connected apps, share links, branding, top-ups — who and when. Free.

- **Cost:** Free
- **Who:** Owners and admins. Listed for: Owners and admins, on any connection. OAuth scope `peekrank:read`.
- **Hints:** read-only · idempotent
- **In the app:** [Settings → Security](/team/settings/)

| Input | Type | |
|---|---|---|
| `limit` | `integer` | Events (default 50). ≥ 1, ≤ 100. |

Ask your assistant: *“Who created share links or changed roles recently?”*

### revoke_connection

**Revoke a connection or API key.** Cuts off a connected AI app (mcpc_…) or an API key from list_connections: it stops on its next call (this one too, if it's yours). Ask the user first.

- **Cost:** Set-up, nothing billed in the call
- **Who:** Owners and admins. Listed for: Owners and admins who ticked "Also manage the workspace" when connecting their AI app (never API keys). OAuth scope `peekrank:manage`.
- **Hints:** changes data · destructive · idempotent
- **In the app:** [Settings → Developers &amp; AI](/ai/access/)

| Input | Type | |
|---|---|---|
| `id` | `string` | **Required.** A connection (mcpc_…) or API key id from list_connections. Up to 64 characters. |

Ask your assistant: *“Disconnect the old Cursor connection.”*