API Introduction

The SnowSEO API lets you access your SEO data programmatically. Use it to run audits, check keyword rankings, fetch analytics, or embed SnowSEO data into your own dashboards, scripts, and integrations.

The API is available on the Scale plan. Generate API keys from Settings → Integrations → API in your dashboard. A brand key works for one brand; an organization key works for every brand in the organization. Only organization admins and owners can create or delete keys.

Base URL

All API requests go to this base URL:

https://api.snowseo.com

Every endpoint path starts with /v3, for example https://api.snowseo.com/v3/seo-audit. Responses are JSON, except long-running endpoints such as a single-page POST /v3/seo-audit, which stream newline-delimited JSON (see Streaming responses). Send request bodies as JSON with the Content-Type: application/json header.

What You Can Do With the API

Use Case	Example
Run site audits	Check any website’s SEO health score and get detailed findings
Track keywords	Add, list, and monitor keyword rankings over time
Fetch traffic data	Pull GSC and Google Analytics metrics for your articles
Manage articles	List, create, and publish content via connected CMS
Read brand settings	Pull brand info, target audience, and competitors
Build dashboards	Pipe SnowSEO data into your own BI tools or internal reports

Authentication

All endpoints require an API key in the Authorization header:

Authorization: Bearer sk_team_your_key_here

The key can also be sent in an x-api-key header. Brand keys start with sk_team_ (older ones with sk_) and organization keys with sk_org_. Both are generated in Settings → Integrations → API. See the Authentication guide for full details on creating keys, scoping, and security best practices.

How to Make a Request

Here’s the typical pattern for any API call:

# 1. Choose an endpoint
# 2. Set the Authorization header
# 3. Send JSON body (for POST/PUT requests)

curl -X POST https://api.snowseo.com/v3/seo-audit \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "example.com"}'

For GET requests, pass parameters as query strings:

curl "https://api.snowseo.com/v3/rank-tracking/keywords" \
  -H "Authorization: Bearer YOUR_API_KEY"

Your First Integration

Here’s a minimal Node.js example to get you started:

const SNOWSEO_API_KEY = process.env.SNOWSEO_API_KEY;
const BASE_URL = 'https://api.snowseo.com';

async function auditSite(url) {
  const response = await fetch(`${BASE_URL}/v3/seo-audit`, {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${SNOWSEO_API_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ url }),
  });

  if (!response.ok) {
    throw new Error(`API error: ${response.status}`);
  }

  // The audit streams NDJSON: status lines first, the result on the last line
  const lines = (await response.text()).split('\n').filter((l) => l.trim());
  const result = JSON.parse(lines.at(-1));
  if (result.error) {
    throw new Error(result.error);
  }
  return result;
}

// Run it
auditSite('example.com').then(data => {
  console.log(`SEO Score: ${data.seoAudit.overallScore}/100`);
});

A brand key carries your brand automatically, so there is no teamId to pass. With an organization key, pass the brand’s teamId on each request.

Endpoints Overview

The API is organized into these categories:

Group	Description
Website Analysis	Audits, health scores, and page findings
Keywords & Research	Keyword research, suggestions, search history
Traffic & Analytics	GSC and Google Analytics data
Rank Tracking	Tracked keywords, position history, changes
Content	Article management and CMS integration
Dashboard	Activity feed and overview data
Settings	Brand settings and configuration

Browse all endpoints using the navigation on the left.

Date Windows

Endpoints that take a date window accept either startDate and endDate (YYYY-MM-DD) or days.

days counts back from today on the team’s calendar, in the team’s time zone (UTC if the team has none).
The API turns days into startDate and endDate before reading any data, so every number in one response covers the same window.
days is ignored when startDate or endDate is sent.
With no window, endpoints use the last 30 days. Keyword history defaults to 90 days, the keyword timeline to 365, and the AI visibility prompt list to your full history.
endDate without startDate means All Time where the endpoint supports it.
startDate without endDate runs to today on the team’s calendar.
Search Console data lags 2-3 days, so a window ending today is clamped to Google’s newest day.

Response Format

Successful responses return the data directly:

{
  "url": "https://example.com",
  "seoAudit": {
    "overallScore": 87,
    "totalTests": 32,
    "passedTests": 28
  }
}

Every error response has the same shape: success: false, a human-readable error, and a machine-readable code. Some add fields that explain more (for example requiredCredits, retryAfterSeconds, featureId), and a 500 adds a reference to quote to support.

{
  "success": false,
  "error": "Team not found",
  "code": "TEAM_NOT_FOUND"
}

Branch on code, not on the error text. Without a more specific code, code falls back to the HTTP status: BAD_REQUEST, UNAUTHORIZED, PAYMENT_REQUIRED, FORBIDDEN, NOT_FOUND, CONFLICT, UNPROCESSABLE, TOO_MANY_REQUESTS, INTERNAL_ERROR, UPSTREAM_ERROR, SERVICE_UNAVAILABLE. Common specific codes:

Code	Meaning
`TEAM_ID_REQUIRED`	The request needs a `teamId`
`NOT_TEAM_MEMBER`, `NOT_TEAM_ADMIN`, `NOT_TEAM_OWNER`	Your role on the brand is not enough
`PLAN_REQUIRED`	No active plan (`reason` says why)
`FEATURE_NOT_AVAILABLE`	Your plan does not include this feature (`featureId` says which)
`INSUFFICIENT_CREDITS`	Not enough credits (`requiredCredits` when known)
`USAGE_LIMIT_REACHED`	A usage limit was hit
`SCALE_PLAN_REQUIRED`	The Scale plan is required
`FST_ERR_VALIDATION`	The request body or query failed validation
`MCP_TOOL_DISABLED`	The tool is turned off for this brand

A few endpoints, such as IndexNow, also return message.

Streaming responses

Long-running endpoints (a single-page POST /v3/seo-audit, for example) reply with Content-Type: application/x-ndjson. The stream sends blank keep-alive whitespace and {"status": "..."} lines, then the result as the last JSON line. Once streaming starts the HTTP status is already 200, so a failure arrives in-band as a final {"success": false, "error": "...", "code": "..."} line. Read the response line by line and check the last line for error. Validation, plan, and conflict errors are returned before streaming starts, with a real status code.

Rate Limits

Limits apply at three levels:

Per API key: 120 requests per 60 seconds.
Per route: varies by endpoint, for example 100 requests per minute for /v3/seo-audit and 150 for rank-tracking endpoints.
Global: 240 requests per minute for the organization.

When any of these limits is hit, the API returns 429 with a retryAfterSeconds hint:

{
  "success": false,
  "statusCode": 429,
  "code": "TOO_MANY_REQUESTS",
  "error": "Rate limit exceeded.",
  "message": "Rate limit exceeded.",
  "retryAfterSeconds": 60
}

Handling rate limits:

Wait for the number of seconds indicated by retryAfterSeconds
If you don’t have a retryAfterSeconds value, use exponential backoff (1s, 2s, 4s, 8s…)
If you’re regularly hitting the limit, batch your requests or add delays between calls

Error Handling

The API uses standard HTTP status codes:

Code	Meaning
`200`	Success
`201`	Created
`400`	Bad request - check your parameters
`401`	Unauthorized - invalid or missing API key
`402`	Payment required - not enough credits or balance for this operation
`403`	Forbidden - valid key but no access, or a plan or usage limit was hit (for example `SCALE_PLAN_REQUIRED`)
`404`	Not found
`409`	Conflict - the resource is busy or already exists, for example an audit already running
`422`	Unprocessable - the request is valid but cannot be applied, for example a sitemap on another domain
`429`	Rate limited
`500`	Internal error - something went wrong on our end
`502`	Upstream error - a connected service (Google, your CMS, your mail server) failed or rejected the call
`503`	Service unavailable - try again later

Always check both the HTTP status code and the error field in the response body:

const response = await fetch(url, options);

if (!response.ok) {
  const error = await response.json();
  console.log(error.error);    // Human-readable message, e.g. "Rate limit exceeded."
  console.log(error.code);      // Always present, e.g. "UNAUTHORIZED"
  // Handle accordingly
}

Testing with cURL

The quickest way to test the API is with cURL from your terminal:

# Check your API key is working
curl https://api.snowseo.com/v3/rank-tracking/keywords \
  -H "Authorization: Bearer YOUR_KEY"

# Run a site audit (streams NDJSON; the result is the last line)
curl -N -X POST https://api.snowseo.com/v3/seo-audit \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "example.com"}'

# List tracked keywords
curl https://api.snowseo.com/v3/rank-tracking/keywords \
  -H "Authorization: Bearer YOUR_KEY"

SDKs & Client Libraries

Currently, the API is raw HTTP - no official SDK yet. The authentication guide has examples in Node.js and Python that you can copy into your project. If you build a client library, let us know and we can list it here.

Need Help?

Errors? Check the error handling section in the Authentication guide.
Questions? Email support@snowseo.com.
Bugs or missing features? Open an issue on our GitHub.

Overview

Website Analysis

PageSpeed

Pages & Folders

Keywords & Research

Topic Clusters

Traffic & Analytics

AI Visibility

Rank Tracking

Article Generation

Content

Content Utilities

Backlink Outreach

Exports

Reports

Dashboard

Ask Snowy

Settings

API Introduction

Base URL

What You Can Do With the API

Authentication

How to Make a Request

Your First Integration

Endpoints Overview

Date Windows

Response Format

Streaming responses

Rate Limits

Error Handling

Testing with cURL

SDKs & Client Libraries

Need Help?

​Base URL

​What You Can Do With the API

​Authentication

​How to Make a Request

​Your First Integration

​Endpoints Overview

​Date Windows

​Response Format

​Streaming responses

​Rate Limits

​Error Handling

​Testing with cURL

​SDKs & Client Libraries

​Need Help?

Base URL

What You Can Do With the API

Authentication

How to Make a Request

Your First Integration

Endpoints Overview

Date Windows

Response Format

Streaming responses

Rate Limits

Error Handling

Testing with cURL

SDKs & Client Libraries

Need Help?