---
title: "Start an internal link analysis"
method: POST
path: "/v3/site-linking/run"
tags: ["Internal Linking"]
---

# Start an internal link analysis

`POST /v3/site-linking/run`

## Request

- Base URL: `https://api.snowseo.com`
- URL: `https://api.snowseo.com/v3/site-linking/run`
- Auth: one of:
  - HTTP bearer
  - API key in header `x-api-key`

Has AI read the brand's crawled pages and suggest internal links worth adding. This SPENDS AI CREDITS, 1 per page read - always tell the user how many pages and credits first (from internal_link_analysis) and get their go-ahead. `mode` 'changed' reads only pages that are new or changed since the last analysis; 'all' reads every page again. `scope` narrows it to one folder, one topic group or up to 500 specific pages; leave it out for the whole site. Suggested links can point anywhere on the site whatever the scope. To get links pointing TO one page instead (for a page nothing links to), use scope kind 'linksTo' with its address: AI picks up to 5 pages that talk about its subject, reads them, and it costs 1 credit in total. Nothing on the live site changes: it only produces suggestions to review with internal_link_suggestions. Runs in the background, one at a time per brand; poll internal_link_analysis for progress. Returns 402 when the credits do not cover it.

## Request body

- object
  - `teamId` string, required: SnowSEO team ID. Call list_teams first to choose a team.
  - `mode` 'changed' | 'all': 'changed' for pages new or changed since the last analysis, 'all' for every page. Defaults to 'all'.
  - `scope` object: Narrows which pages are read. Set `kind` and the one field that goes with it.
    - `kind` 'folder' | 'topic' | 'pages' | 'linksTo', required
    - `url` string: With kind 'linksTo': the full address of a page that needs incoming links. Reads up to 5 pages likeliest to mention it and only suggests links pointing to it. Costs 1 AI credit in total. `mode` is ignored.
    - `folder` string: With kind 'folder': a path such as '/blog' or '/blog/guides'. Reads that page and everything under it.
    - `clusterId` string: With kind 'topic': the id of a topic group from internal_link_analysis.
    - `urls` string[]: With kind 'pages': the full addresses of the pages.

## Response `200`

Default Response

## Changes

- **2026-10-12** `09cbe0d8a50f`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/snowseo/apis/snowseo-api/changes/v3/site-linking/run/post.md)

---

[API](https://skmtc.dev/snowseo/apis/snowseo-api.md) - [All operations](https://skmtc.dev/snowseo/apis/snowseo-api/llms.txt) - [OpenAPI document](https://skmtc.dev/snowseo/apis/snowseo-api/revisions/ac69ae8943d7?raw)