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 (
startandend) default to the 28 days ending today. If you send onlyend,startdefaults to 27 days before it.endcan't be in the future,startmust be on or beforeend, andstartcan be at most 16 months ago. - Sites are identified by the
idreturned by List sites. A site the key can't read, or that doesn't exist, returns404. - 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.connectedis whether the organization owner has a Google connection stored.rankTracking.serpApiConfiguredis 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
}
]
}
isActiveis whether it's the site currently selected in the app.ga4shows the GA4 property linked to the site in Settings β API access.trackedKeywordsis the number of rank tracking keywords on the site.
Find a site by domain
GET /sites/match?domain=example.com
| Parameter | Required | Notes |
|---|---|---|
domain | Yes | A 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.
| Parameter | Default | Notes |
|---|---|---|
start, end | The last 28 days | See Conventions |
dimension | date | date, query or page |
limit | 100 | 1 to 1,000. Applies to query and page rows |
compare | None | previous 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,queryorpageas their first field, depending ondimension.daterows are oldest first;queryandpagerows are most clicks first. previousis only included when you ask forcompare=previous.totalscome from the site's daily totals, so they can be higher than the sum of thequeryrows. 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.
| Parameter | Default | Notes |
|---|---|---|
start, end | The last 28 days | See Conventions |
view | overview | overview, organic_landing_pages or channels |
limit | 100 | 1 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.
| Parameter | Default | Notes |
|---|---|---|
history_days | None | 1 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" }
]
}
]
}
historyDaysandhistoryare only included when you sendhistory_days. History is oldest first.outsideTop100istruewhen the latest check was a SerpAPI check that didn't find the site.methodin 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.
| Parameter | Default | Notes |
|---|---|---|
days | 30 | 1 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,bestPositionandworstPositionuse only checks that found a position. They'renullwhen none did.foundRateis 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