Features πŸš€ SaaS πŸ›’ Ecommerce 🏒 Agencies πŸ“ Local Business πŸ“š Glossary πŸ“– Docs Chrome Extension Pricing Log in Get Started

Docs / Developers

Endpoint reference

Every SEObolt API endpoint, its parameters and the shape of its response.

All endpoints are relative to the base URL:

https://app.seobolt.io/api/v1

All are GET. Every response is JSON and is sent with Cache-Control: no-store.

Conventions

  • Dates are YYYY-MM-DD, in UTC.
  • Date ranges (start and end) default to the 28 days ending today. If you send only end, start defaults to 27 days before it. end can't be in the future, start must be on or before end, and start can be at most 16 months ago.
  • Sites are identified by the id returned by List sites. A site the key can't read, or that doesn't exist, returns 404.
  • CTR is a percentage. Position is an average weighted by impressions.

Connection test

GET /me

Checks the key and shows what it's connected to.

{
  "organization": { "id": 7, "name": "Acme Agency", "tier": "agency" },
  "key": { "name": "Royally", "keyPrefix": "sbk_AbCdEfGh", "createdAt": "2026-10-11T00:00:00.000Z" },
  "google": { "connected": true },
  "rankTracking": { "serpApiConfigured": true }
}
  • google.connected is whether the organization owner has a Google connection stored.
  • rankTracking.serpApiConfigured is whether the owner has added a SerpAPI key.

List sites

GET /sites

Every Search Console site the key can read, sorted by URL. This includes all the owner's sites, not only the one active in the app.

{
  "sites": [
    {
      "id": 5,
      "siteUrl": "https://example.com/",
      "domain": "example.com",
      "isActive": true,
      "lastSynced": "2026-10-11T04:00:00.000Z",
      "permissionLevel": "siteOwner",
      "ga4": { "linked": true, "propertyId": "123456789" },
      "trackedKeywords": 12
    }
  ]
}
  • isActive is whether it's the site currently selected in the app.
  • ga4 shows the GA4 property linked to the site in Settings β†’ API access.
  • trackedKeywords is the number of rank tracking keywords on the site.

Find a site by domain

GET /sites/match?domain=example.com
ParameterRequiredNotes
domainYesA domain name or URL, such as example.com or https://www.example.com/blog

Returns the best matching site the key can read. A URL-prefix property for the exact domain wins (https before http, then the shortest path). Otherwise the closest domain property (sc-domain:) is used: the exact domain first, then a parent domain, so blog.example.com can match sc-domain:example.com. A leading www. is ignored, so www.example.com and example.com match the same sites.

{
  "site": {
    "id": 5,
    "siteUrl": "https://example.com/",
    "domain": "example.com",
    "isActive": true,
    "lastSynced": "2026-10-11T04:00:00.000Z",
    "permissionLevel": "siteOwner",
    "ga4": { "linked": true, "propertyId": "123456789" },
    "trackedKeywords": 12
  }
}

No match returns 404 not_found. A missing or invalid domain returns 400 bad_request.

Search performance

GET /sites/{id}/search-performance

Search Console clicks, impressions, CTR and position.

ParameterDefaultNotes
start, endThe last 28 daysSee Conventions
dimensiondatedate, query or page
limit1001 to 1,000. Applies to query and page rows
compareNoneprevious adds totals for the period of the same length just before

Example: GET /sites/5/search-performance?dimension=query&limit=50&compare=previous

{
  "site": { "id": 5, "siteUrl": "https://example.com/" },
  "range": { "start": "2026-09-14", "end": "2026-10-11" },
  "dimension": "query",
  "source": "stored",
  "totals": { "clicks": 310, "impressions": 12040, "ctr": 2.57, "position": 14.2 },
  "previous": {
    "range": { "start": "2026-08-17", "end": "2026-09-13" },
    "totals": { "clicks": 280, "impressions": 11100, "ctr": 2.52, "position": 15.1 }
  },
  "rows": [
    { "query": "seo dashboard", "clicks": 40, "impressions": 900, "ctr": 4.44, "position": 6.1 }
  ]
}
  • Rows use date, query or page as their first field, depending on dimension. date rows are oldest first; query and page rows are most clicks first.
  • previous is only included when you ask for compare=previous.
  • totals come from the site's daily totals, so they can be higher than the sum of the query rows. Google leaves rare queries out of query-level data.

Where the numbers come from. source is "stored" when the whole range (including the comparison period) falls within the last 90 days and the site synced in the last 48 hours. SEObolt then answers from its synced data. Otherwise source is "live": SEObolt asks Google, which counts toward the daily Google limit. Live responses also include "cached": true or false, and "stale": true when Google failed and an older cached copy was returned.

Site analytics (GA4)

GET /sites/{id}/analytics

Google Analytics 4 numbers for the GA4 property linked to the site. Link one on the GA4 property per site card in Settings β†’ API access. A site with no linked property returns 409 ga4_not_linked.

ParameterDefaultNotes
start, endThe last 28 daysSee Conventions
viewoverviewoverview, organic_landing_pages or channels
limit1001 to 1,000 rows

GA4 data is always live (source is "live") and is cached for 6 hours.

overview returns totals for the range and for the period of the same length just before:

{
  "site": { "id": 5, "siteUrl": "https://example.com/" },
  "ga4": { "propertyId": "123456789" },
  "view": "overview",
  "range": { "start": "2026-09-14", "end": "2026-10-11" },
  "source": "live",
  "cached": false,
  "totals": {
    "sessions": 4200, "totalUsers": 3100, "newUsers": 2500,
    "screenPageViews": 9800, "averageSessionDuration": 74.2, "bounceRate": 48.5
  },
  "previous": {
    "range": { "start": "2026-08-17", "end": "2026-09-13" },
    "totals": {
      "sessions": 3900, "totalUsers": 2900, "newUsers": 2300,
      "screenPageViews": 9100, "averageSessionDuration": 70.8, "bounceRate": 50.1
    }
  }
}

averageSessionDuration is in seconds and bounceRate is a percentage.

organic_landing_pages returns landing pages for Organic Search sessions only, most sessions first. Each row has landingPage and the same six metrics as overview:

{
  "rows": [
    {
      "landingPage": "/blog/seo-checklist",
      "sessions": 820, "totalUsers": 700, "newUsers": 610,
      "screenPageViews": 1500, "averageSessionDuration": 95.3, "bounceRate": 41.2
    }
  ]
}

channels returns sessions by default channel group, most sessions first:

{
  "rows": [
    { "channel": "Organic Search", "sessions": 2100, "totalUsers": 1600, "newUsers": 1300 }
  ]
}

The organic_landing_pages and channels responses also include site, ga4, view, range, source and cached, as in overview.

Tracked keywords

GET /sites/{id}/rankings

The site's rank tracking keywords, most recently added first.

ParameterDefaultNotes
history_daysNone1 to 90. Adds each keyword's checks from that many days back
{
  "site": { "id": 5, "siteUrl": "https://example.com/" },
  "historyDays": 30,
  "keywords": [
    {
      "id": 81,
      "keyword": "seo dashboard",
      "targetUrl": null,
      "location": "United States",
      "device": "desktop",
      "currentPosition": 7,
      "bestPosition": 4,
      "avgPosition": 8.3,
      "lastChecked": "2026-10-10T06:00:00.000Z",
      "outsideTop100": false,
      "history": [
        { "position": 7, "found": true, "method": "serpapi", "checkedAt": "2026-10-10T06:00:00.000Z" }
      ]
    }
  ]
}
  • historyDays and history are only included when you send history_days. History is oldest first.
  • outsideTop100 is true when the latest check was a SerpAPI check that didn't find the site.
  • method in history says how the position was found, for example from Search Console or SerpAPI.

Keyword history

GET /sites/{id}/rankings/{keywordId}/history

One tracked keyword's checks over time, with summary stats. keywordId is the id from Tracked keywords.

ParameterDefaultNotes
days301 to 90
{
  "site": { "id": 5, "siteUrl": "https://example.com/" },
  "keyword": { "id": 81, "keyword": "seo dashboard", "targetUrl": null },
  "days": 30,
  "history": [
    { "position": 9, "found": true, "method": "gsc", "checkedAt": "2026-09-20T06:00:00.000Z" },
    { "position": 7, "found": true, "method": "serpapi", "checkedAt": "2026-10-10T06:00:00.000Z" }
  ],
  "stats": {
    "totalChecks": 2,
    "avgPosition": 8,
    "bestPosition": 7,
    "worstPosition": 9,
    "foundRate": 100
  }
}
  • avgPosition, bestPosition and worstPosition use only checks that found a position. They're null when none did.
  • foundRate is the percentage of checks that found the site.
  • A keyword that isn't on this site returns 404 not_found.

Anything else

Any other path returns 404 not_found with "No such endpoint." Any method other than GET or HEAD returns 405 method_not_allowed. See Rate limits and errors.

Last updated 2026-10-28