Semalt for developers

Public API v1

Read and manage account websites, analytics organization, campaign keywords, and indexing through a stable, AI-friendly HTTP API.

OpenAPI JSON OpenAPI YAML MCP server

Developer access

Get your Semalt API key

Create a free Semalt account to access the Public API and connect AI tools through MCP.

Loading API access...

Quick start

Authenticate every request with the API key from your Semalt account using the Authorization: Bearer header.

curl 'https://semalt.com/api/v1/sites?limit=25' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Accept: application/json'

Base URLhttps://semalt.com/api/v1

For POST requests Send the body as JSON

Every write endpoint accepts one JSON object and requires Content-Type: application/json. Endpoints that do not need fields still expect an empty JSON object: {}.

curl --request POST \
  --url 'https://semalt.com/api/v1/sites' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{"domain":"example.com"}'

Site records

Site collections preserve each accessible website record without grouping by domain or Search Console property. Repeated domains or properties are intentional when they are available through several accounts.

access_type=own — owned by the authenticated account.
access_type=linked — owned by a linked account.
access_type=shared — available to this account without direct or linked ownership.

Hidden and removed records are excluded. Use the returned id for every detail request. My SEO campaign data is exposed only when the authenticated account has a campaign for the site's domain.

Account

Authenticated Semalt account information.

GET /me

Get the authenticated account

Returns the account associated with the authenticated API key and the account ids linked to it.

Sites

Website records available to the authenticated account.

GET /sites

List accessible sites

Returns website records available to the authenticated account. Records are not grouped, so the same domain can appear more than once when it is available through different accounts or properties.

limit query · optional · integer · default: 50

Maximum number of site records to return in this cursor page. The API may return fewer records; use has_more and next_cursor to continue.

cursor query · optional · string

Continuation cursor from the previous response meta.next_cursor. Omit it for the first page and treat its value as opaque.

search query · optional · string

Case-insensitive substring matched against the website domain and, when present, its Search Console property URL.

tag_ids query · optional · array<integer>

Comma-separated site tag ids from GET /site-tags. By default a site may match any supplied tag; use tag_match=all to require every tag.

tag_match query · optional · string · any | all · default: any

How tag_ids are combined: any returns a site with at least one selected tag; all requires every selected tag.

exclude_tag_ids query · optional · array<integer>

Comma-separated site tag ids. Sites carrying any excluded tag are omitted.

site_type query · optional · string · gsc | manual

Return only Search Console-connected records (gsc) or manually added records (manual).

access_type query · optional · string · own | linked | shared

Filter by how this account can access the site: direct ownership, a linked account, or another available account relationship.

has_search_console query · optional · boolean

When true, return only records connected to a usable Search Console property; when false, return records without one.

POST /sites

Add a website

Creates or restores a manual website for the authenticated account. The operation is idempotent by normalized domain: adding the same domain again returns its existing site record.

Request body application/json one JSON object

Website to add. A complete URL is accepted and normalized to its domain.

domain body · required · string

Public domain or HTTP/HTTPS URL.

JSON body example

{
  "domain": "example.com"
}

GET /sites/{site_id}

Get one site

Use an id returned by a site collection. The request returns 404 when the site is hidden, removed, unknown, or not accessible to the current account.

site_id path · required · integer

Stable site identifier returned by a site collection endpoint.

Site Tags

Personal labels for organizing and filtering accessible domains.

GET /site-tags

List site tags

Returns personal site tags with the number of accessible domains assigned to each tag.

POST /site-tags

Create a site tag

Creates a tag for the linked account group. Repeating the same normalized name updates and returns the existing tag.

Request body application/json one JSON object

Tag name and optional display color.

name body · required · string

color body · optional · string | null

Optional six-digit hex color.

JSON body example

{
  "name": "Priority",
  "color": "#dc2626"
}

POST /site-tags/{tag_id}

Update a site tag

Renames a tag and optionally changes its color.

Request body application/json one JSON object

Complete editable tag fields.

tag_id path · required · integer

Site tag identifier returned by GET /site-tags.

name body · required · string

color body · optional · string | null

JSON body example

{
  "name": "Important",
  "color": "#dc2626"
}

POST /site-tags/{tag_id}/delete

Delete a site tag

Permanently deletes the tag and all of its domain assignments. Confirm this destructive action with the user before calling it.

Request body application/json one JSON object

Send an empty JSON object to confirm the request shape.

tag_id path · required · integer

Site tag identifier returned by GET /site-tags.

JSON body example

{}

GET /site-tags/{tag_id}/sites

List sites assigned to a tag

Returns accessible domains assigned to the selected tag. search is a case-insensitive domain substring.

tag_id path · required · integer

Site tag identifier returned by GET /site-tags.

page query · optional · integer · default: 1

One-based result page number. Use 1 for the first page.

page_size query · optional · integer · default: 50

Maximum number of items in one page. Public API responses cap this value at 200; some product datasets may apply a lower internal cap.

search query · optional · string

Case-insensitive substring matched against assigned domains.

POST /site-tags/{tag_id}/sites

Assign a tag to sites

Assigns the selected tag to each supplied accessible domain. Existing assignments are left unchanged.

Request body application/json one JSON object

Domains that should receive the tag.

tag_id path · required · integer

Site tag identifier returned by GET /site-tags.

domains body · required · array<string>

JSON body example

{
  "domains": [
    "example.com",
    "shop.example.com"
  ]
}

POST /site-tags/{tag_id}/sites/remove

Remove a tag from sites

Removes the selected tag from supplied accessible domains. Confirm the affected domains with the user before calling it.

Request body application/json one JSON object

Domains from which the tag should be removed.

tag_id path · required · integer

Site tag identifier returned by GET /site-tags.

domains body · required · array<string>

JSON body example

{
  "domains": [
    "example.com"
  ]
}

Keyword Groups

Reusable, site-specific keyword collections used as analytics filters.

GET /sites/{site_id}/keyword-groups

List keyword groups

Returns reusable keyword groups visible for the selected site. Groups identify their owner and whether the authenticated account can edit them.

site_id path · required · integer

Stable site identifier returned by a site collection endpoint.

POST /sites/{site_id}/keyword-groups

Create a keyword group

Creates a personal reusable keyword group for the domain represented by site_id.

Request body application/json one JSON object

Name for the new group.

site_id path · required · integer

Stable site identifier returned by a site collection endpoint.

name body · required · string

JSON body example

{
  "name": "Commercial keywords"
}

POST /sites/{site_id}/keyword-groups/{group_id}

Rename a keyword group

Renames an editable non-default keyword group.

Request body application/json one JSON object

New group name.

site_id path · required · integer

Stable site identifier returned by a site collection endpoint.

group_id path · required · integer

Keyword group identifier returned for the selected site.

name body · required · string

JSON body example

{
  "name": "High-intent keywords"
}

POST /sites/{site_id}/keyword-groups/{group_id}/delete

Delete a keyword group

Permanently deletes an editable non-default group and its keyword membership. Confirm this destructive action before calling it.

Request body application/json one JSON object

Send an empty JSON object to confirm the request shape.

site_id path · required · integer

Stable site identifier returned by a site collection endpoint.

group_id path · required · integer

Keyword group identifier returned for the selected site.

JSON body example

{}

GET /sites/{site_id}/keyword-groups/{group_id}/keywords

List group keywords

Returns keyword rows stored in one reusable group. search is a case-insensitive keyword substring.

site_id path · required · integer

Stable site identifier returned by a site collection endpoint.

group_id path · required · integer

Keyword group identifier returned for the selected site.

page query · optional · integer · default: 1

One-based result page number. Use 1 for the first page.

page_size query · optional · integer · default: 50

Maximum number of items in one page. Public API responses cap this value at 200; some product datasets may apply a lower internal cap.

search query · optional · string

Text used to narrow keyword or query results. For Google SERP token search, provide at least four characters.

POST /sites/{site_id}/keyword-groups/{group_id}/keywords

Add keywords to a group

Adds normalized keywords to an editable group. Exact duplicates are skipped and reported, so retrying the same payload is safe.

Request body application/json one JSON object

Keyword text values to add.

site_id path · required · integer

Stable site identifier returned by a site collection endpoint.

group_id path · required · integer

Keyword group identifier returned for the selected site.

keywords body · required · array<string>

JSON body example

{
  "keywords": [
    "technical seo audit",
    "managed seo services"
  ]
}

POST /sites/{site_id}/keyword-groups/{group_id}/keywords/remove

Remove keywords from a group

Removes keyword rows by ids returned by the group keyword list. Confirm the affected rows before calling it.

Request body application/json one JSON object

Keyword row ids to remove.

site_id path · required · integer

Stable site identifier returned by a site collection endpoint.

group_id path · required · integer

Keyword group identifier returned for the selected site.

keyword_ids body · required · array<integer>

JSON body example

{
  "keyword_ids": [
    123,
    124
  ]
}

Search Console

Google Search Console properties and their analytics.

GET /search-console/sites

List Search Console properties

Returns accessible Search Console properties with current and previous metrics for each record on this cursor page. By default, the current period ends yesterday and covers the preceding 29 inclusive calendar dates.

limit query · optional · integer · default: 50

Maximum number of site records to return in this cursor page. The API may return fewer records; use has_more and next_cursor to continue.

cursor query · optional · string

Continuation cursor from the previous response meta.next_cursor. Omit it for the first page and treat its value as opaque.

search query · optional · string

Case-insensitive substring matched against the website domain and, when present, its Search Console property URL.

tag_ids query · optional · array<integer>

Comma-separated site tag ids from GET /site-tags. By default a site may match any supplied tag; use tag_match=all to require every tag.

tag_match query · optional · string · any | all · default: any

How tag_ids are combined: any returns a site with at least one selected tag; all requires every selected tag.

exclude_tag_ids query · optional · array<integer>

Comma-separated site tag ids. Sites carrying any excluded tag are omitted.

access_type query · optional · string · own | linked | shared

Filter by how this account can access the site: direct ownership, a linked account, or another available account relationship.

date_from query · optional · string

Inclusive first calendar date of the requested analytics period in YYYY-MM-DD format. If omitted, the endpoint selects a recent default period.

date_to query · optional · string

Inclusive last calendar date of the requested analytics period in YYYY-MM-DD format. If both dates are supplied in reverse order, site summaries normalize their order.

GET /search-console/sites/{site_id}/overview

Get Search Console overview

Returns summary cards and daily charts for the exact Search Console property associated with site_id.

site_id path · required · integer

Stable site identifier returned by a site collection endpoint.

date_from query · optional · string

Inclusive first calendar date of the requested analytics period in YYYY-MM-DD format. If omitted, the endpoint selects a recent default period.

date_to query · optional · string

Inclusive last calendar date of the requested analytics period in YYYY-MM-DD format. If both dates are supplied in reverse order, site summaries normalize their order.

GET /search-console/sites/{site_id}/traffic

Get a Search Console traffic series

Returns one daily series for a selected query, page, device, or country. metric chooses which measurement is copied into each item.value; every item also contains clicks, impressions, CTR, and average position for context. Use value to select the exact dimension value.

site_id path · required · integer

Stable site identifier returned by a site collection endpoint.

date_from query · optional · string

Inclusive first calendar date of the requested analytics period in YYYY-MM-DD format. If omitted, the endpoint selects a recent default period.

date_to query · optional · string

Inclusive last calendar date of the requested analytics period in YYYY-MM-DD format. If both dates are supplied in reverse order, site summaries normalize their order.

metric query · optional · string · clicks | impressions | ctr | position · default: position

Selects the measurement written to each traffic-series item.value: clicks is Google result visits, impressions is result appearances, ctr is clicks divided by impressions as a percentage, and position is average Google result position. Each item still includes all four measurements. Default: position.

dimension query · optional · string · query | page | device | country · default: query

Entity represented by value in the traffic series. Use query for a search phrase, page for a page URL, device for desktop/mobile/tablet, or country for a Search Console country code.

value query · optional · string

Exact query text, page URL, device name, or country code whose daily series should be returned. Its meaning is determined by dimension.

device query · optional · string · desktop | mobile | tablet

Restrict Search Console data to one device category.

country query · optional · string

Restrict Search Console data to a canonical country code returned by Search Console, usually a three-character code.

GET /search-console/sites/{site_id}/keywords

List Search Console keywords

Returns aggregated search queries. search matches query text; metric ranges are inclusive and apply before pagination.

site_id path · required · integer

Stable site identifier returned by a site collection endpoint.

search query · optional · string

Case-insensitive substring matched against Search Console query text.

date_from query · optional · string

Inclusive first calendar date of the requested analytics period in YYYY-MM-DD format. If omitted, the endpoint selects a recent default period.

date_to query · optional · string

Inclusive last calendar date of the requested analytics period in YYYY-MM-DD format. If both dates are supplied in reverse order, site summaries normalize their order.

page query · optional · integer · default: 1

One-based result page number. Use 1 for the first page.

page_size query · optional · integer · default: 50

Maximum number of items in one page. Public API responses cap this value at 200; some product datasets may apply a lower internal cap.

device query · optional · string · desktop | mobile | tablet

Restrict Search Console data to one device category.

country query · optional · string

Restrict Search Console data to a canonical country code returned by Search Console, usually a three-character code.

Column used to order aggregated Search Console rows.

sort_direction query · optional · string · ASC | DESC

Sort in ascending (ASC) or descending (DESC) order using sort_by. Defaults are endpoint-specific when omitted.

clicks_min query · optional · number

Keep rows with at least this many clicks.

clicks_max query · optional · number

Keep rows with no more than this many clicks.

impressions_min query · optional · number

Keep rows with at least this many impressions.

impressions_max query · optional · number

Keep rows with no more than this many impressions.

ctr_min query · optional · number

Keep rows with CTR at or above this percentage.

ctr_max query · optional · number

Keep rows with CTR at or below this percentage.

position_min query · optional · number

Keep rows whose average position is at least this numeric value.

position_max query · optional · number

Keep rows whose average position is no greater than this numeric value; useful for TOP 10-style filtering.

GET /search-console/sites/{site_id}/pages

List Search Console pages

Returns aggregated pages. search matches a page URL or path; metric ranges are inclusive and apply before pagination.

site_id path · required · integer

Stable site identifier returned by a site collection endpoint.

search query · optional · string

Case-insensitive substring matched against a Search Console page URL or path.

date_from query · optional · string

Inclusive first calendar date of the requested analytics period in YYYY-MM-DD format. If omitted, the endpoint selects a recent default period.

date_to query · optional · string

Inclusive last calendar date of the requested analytics period in YYYY-MM-DD format. If both dates are supplied in reverse order, site summaries normalize their order.

page query · optional · integer · default: 1

One-based result page number. Use 1 for the first page.

page_size query · optional · integer · default: 50

Maximum number of items in one page. Public API responses cap this value at 200; some product datasets may apply a lower internal cap.

device query · optional · string · desktop | mobile | tablet

Restrict Search Console data to one device category.

country query · optional · string

Restrict Search Console data to a canonical country code returned by Search Console, usually a three-character code.

Column used to order aggregated Search Console rows.

sort_direction query · optional · string · ASC | DESC

Sort in ascending (ASC) or descending (DESC) order using sort_by. Defaults are endpoint-specific when omitted.

clicks_min query · optional · number

Keep rows with at least this many clicks.

clicks_max query · optional · number

Keep rows with no more than this many clicks.

impressions_min query · optional · number

Keep rows with at least this many impressions.

impressions_max query · optional · number

Keep rows with no more than this many impressions.

ctr_min query · optional · number

Keep rows with CTR at or above this percentage.

ctr_max query · optional · number

Keep rows with CTR at or below this percentage.

position_min query · optional · number

Keep rows whose average position is at least this numeric value.

position_max query · optional · number

Keep rows whose average position is no greater than this numeric value; useful for TOP 10-style filtering.

GET /search-console/sites/{site_id}/devices

List Search Console devices

Returns aggregated desktop, mobile, and tablet performance. country can narrow the rows before aggregation.

site_id path · required · integer

Stable site identifier returned by a site collection endpoint.

date_from query · optional · string

Inclusive first calendar date of the requested analytics period in YYYY-MM-DD format. If omitted, the endpoint selects a recent default period.

date_to query · optional · string

Inclusive last calendar date of the requested analytics period in YYYY-MM-DD format. If both dates are supplied in reverse order, site summaries normalize their order.

page query · optional · integer · default: 1

One-based result page number. Use 1 for the first page.

page_size query · optional · integer · default: 50

Maximum number of items in one page. Public API responses cap this value at 200; some product datasets may apply a lower internal cap.

device query · optional · string · desktop | mobile | tablet

Restrict Search Console data to one device category.

country query · optional · string

Restrict Search Console data to a canonical country code returned by Search Console, usually a three-character code.

Column used to order aggregated Search Console rows.

sort_direction query · optional · string · ASC | DESC

Sort in ascending (ASC) or descending (DESC) order using sort_by. Defaults are endpoint-specific when omitted.

clicks_min query · optional · number

Keep rows with at least this many clicks.

clicks_max query · optional · number

Keep rows with no more than this many clicks.

impressions_min query · optional · number

Keep rows with at least this many impressions.

impressions_max query · optional · number

Keep rows with no more than this many impressions.

ctr_min query · optional · number

Keep rows with CTR at or above this percentage.

ctr_max query · optional · number

Keep rows with CTR at or below this percentage.

position_min query · optional · number

Keep rows whose average position is at least this numeric value.

position_max query · optional · number

Keep rows whose average position is no greater than this numeric value; useful for TOP 10-style filtering.

GET /search-console/sites/{site_id}/countries

List Search Console countries

Returns performance grouped by canonical Google Search Console country code. device can narrow the rows before aggregation.

site_id path · required · integer

Stable site identifier returned by a site collection endpoint.

date_from query · optional · string

Inclusive first calendar date of the requested analytics period in YYYY-MM-DD format. If omitted, the endpoint selects a recent default period.

date_to query · optional · string

Inclusive last calendar date of the requested analytics period in YYYY-MM-DD format. If both dates are supplied in reverse order, site summaries normalize their order.

page query · optional · integer · default: 1

One-based result page number. Use 1 for the first page.

page_size query · optional · integer · default: 50

Maximum number of items in one page. Public API responses cap this value at 200; some product datasets may apply a lower internal cap.

device query · optional · string · desktop | mobile | tablet

Restrict Search Console data to one device category.

country query · optional · string

Restrict Search Console data to a canonical country code returned by Search Console, usually a three-character code.

Column used to order aggregated Search Console rows.

sort_direction query · optional · string · ASC | DESC

Sort in ascending (ASC) or descending (DESC) order using sort_by. Defaults are endpoint-specific when omitted.

clicks_min query · optional · number

Keep rows with at least this many clicks.

clicks_max query · optional · number

Keep rows with no more than this many clicks.

impressions_min query · optional · number

Keep rows with at least this many impressions.

impressions_max query · optional · number

Keep rows with no more than this many impressions.

ctr_min query · optional · number

Keep rows with CTR at or above this percentage.

ctr_max query · optional · number

Keep rows with CTR at or below this percentage.

position_min query · optional · number

Keep rows whose average position is at least this numeric value.

position_max query · optional · number

Keep rows whose average position is no greater than this numeric value; useful for TOP 10-style filtering.

Google SERP

Google ranking analytics resolved from an accessible website.

GET /google-serp/sites

List sites with Google SERP metrics

Returns accessible site records with ranking statistics joined by normalized domain. The same domain remains separate when it is accessible through more than one account record. The default date range ends today.

limit query · optional · integer · default: 50

Maximum number of site records to return in this cursor page. The API may return fewer records; use has_more and next_cursor to continue.

cursor query · optional · string

Continuation cursor from the previous response meta.next_cursor. Omit it for the first page and treat its value as opaque.

search query · optional · string

Case-insensitive substring matched against the website domain and, when present, its Search Console property URL.

tag_ids query · optional · array<integer>

Comma-separated site tag ids from GET /site-tags. By default a site may match any supplied tag; use tag_match=all to require every tag.

tag_match query · optional · string · any | all · default: any

How tag_ids are combined: any returns a site with at least one selected tag; all requires every selected tag.

exclude_tag_ids query · optional · array<integer>

Comma-separated site tag ids. Sites carrying any excluded tag are omitted.

date_from query · optional · string

Inclusive first calendar date of the requested analytics period in YYYY-MM-DD format. If omitted, the endpoint selects a recent default period.

date_to query · optional · string

Inclusive last calendar date of the requested analytics period in YYYY-MM-DD format. If both dates are supplied in reverse order, site summaries normalize their order.

search_engine_id query · optional · integer · default: 1

Numeric search-engine/location identifier returned by Semalt analytics. The default value 1 is the standard engine.

site_type query · optional · string · gsc | manual

Return only Search Console-connected records (gsc) or manually added records (manual).

access_type query · optional · string · own | linked | shared

Filter by how this account can access the site: direct ownership, a linked account, or another available account relationship.

GET /google-serp/sites/{site_id}/overview

Get Google SERP overview

Returns site statistics for the selected search engine and date range. If an exact snapshot is unavailable, the analytics source may use the nearest earlier snapshot.

site_id path · required · integer

Stable site identifier returned by a site collection endpoint.

date_from query · optional · string

Inclusive first calendar date of the requested analytics period in YYYY-MM-DD format. If omitted, the endpoint selects a recent default period.

date_to query · optional · string

Inclusive last calendar date of the requested analytics period in YYYY-MM-DD format. If both dates are supplied in reverse order, site summaries normalize their order.

search_engine_id query · optional · integer · default: 1

Numeric search-engine/location identifier returned by Semalt analytics. The default value 1 is the standard engine.

GET /google-serp/sites/{site_id}/keywords

List Google SERP keyword positions

Returns keyword positions and movement for the domain resolved from site_id. search is a keyword token search and should contain at least four characters. keyword_group_id restricts results to a reusable group visible for this site. Continue cursor pagination with next_token from the result as page_token.

site_id path · required · integer

Stable site identifier returned by a site collection endpoint.

search_engine_id query · optional · integer · default: 1

Numeric search-engine/location identifier returned by Semalt analytics. The default value 1 is the standard engine.

date query · optional · string

Requested snapshot date in YYYY-MM-DD format. When the exact snapshot is unavailable, Google SERP data may come from the nearest earlier snapshot.

search query · optional · string

Text used to narrow keyword or query results. For Google SERP token search, provide at least four characters.

keyword_group_id query · optional · integer

Restrict results to keywords in this reusable group. Obtain the id from GET /sites/{site_id}/keyword-groups; an empty group returns no matching rows.

page_url query · optional · string

Exact page URL or path previously returned by Google SERP analytics.

position_group query · optional · string · top1 | top3 | top10 | quick_wins

Convenience filter for position sets: top1 is position 1, top3 is 1–3, top10 is 1–10, and quick_wins is 4–10.

Filter keywords by movement between snapshots. dynamics means no movement filter.

primary_only query · optional · boolean

When true, return only primary Google SERP position records.

sort_by query · optional · string · key_val | pos | searches | popularity · default: popularity

Column used to order Google SERP keyword rows.

sort_direction query · optional · string · ASC | DESC

Sort in ascending (ASC) or descending (DESC) order using sort_by. Defaults are endpoint-specific when omitted.

page_size query · optional · integer · default: 50

Maximum number of items in one page. Public API responses cap this value at 200; some product datasets may apply a lower internal cap.

page_token query · optional · string

Opaque Google SERP keyword cursor from the previous result next_token. Omit it for the first page.

GET /google-serp/sites/{site_id}/pages

List best Google SERP pages

Returns best-performing pages for the resolved domain. keyword_group_id calculates page metrics only from keywords in a reusable group. page_url and keyword are exact upstream values; numeric minimum and maximum filters are inclusive.

site_id path · required · integer

Stable site identifier returned by a site collection endpoint.

search_engine_id query · optional · integer · default: 1

Numeric search-engine/location identifier returned by Semalt analytics. The default value 1 is the standard engine.

date query · optional · string

Requested snapshot date in YYYY-MM-DD format. When the exact snapshot is unavailable, Google SERP data may come from the nearest earlier snapshot.

keyword_group_id query · optional · integer

Restrict results to keywords in this reusable group. Obtain the id from GET /sites/{site_id}/keyword-groups; an empty group returns no matching rows.

page_url query · optional · string

Exact page URL or path previously returned by Google SERP analytics.

keyword query · optional · string

Exact keyword value previously returned by Google SERP analytics.

queries_min query · optional · number

Keep pages with at least this many tracked queries.

queries_max query · optional · number

Keep pages with no more than this many tracked queries.

average_position_min query · optional · number

Keep pages whose average position is at least this value.

average_position_max query · optional · number

Keep pages whose average position is no greater than this value.

share_percent_min query · optional · number

Keep pages whose visibility share is at least this percentage.

share_percent_max query · optional · number

Keep pages whose visibility share is no greater than this percentage.

rating_min query · optional · number

Keep pages whose rating is at least this value.

rating_max query · optional · number

Keep pages whose rating is no greater than this value.

sort_by query · optional · string · total_queries | keywords | avg_pos | share_percent | rating · default: total_queries

Column used to order Google SERP page rows.

sort_direction query · optional · string · ASC | DESC

Sort in ascending (ASC) or descending (DESC) order using sort_by. Defaults are endpoint-specific when omitted.

page query · optional · integer · default: 1

One-based result page number. Use 1 for the first page.

page_size query · optional · integer · default: 50

Maximum number of items in one page. Public API responses cap this value at 200; some product datasets may apply a lower internal cap.

GET /google-serp/sites/{site_id}/competitors

List Google SERP competitors

Returns the top competitors by shared keywords for the resolved domain.

site_id path · required · integer

Stable site identifier returned by a site collection endpoint.

search_engine_id query · optional · integer · default: 1

Numeric search-engine/location identifier returned by Semalt analytics. The default value 1 is the standard engine.

date query · optional · string

Requested snapshot date in YYYY-MM-DD format. When the exact snapshot is unavailable, Google SERP data may come from the nearest earlier snapshot.

GET /google-serp/rankings

List global Google SERP rankings

Returns a page of global domain rankings for one search engine and snapshot date.

search_engine_id query · optional · integer · default: 1

Numeric search-engine/location identifier returned by Semalt analytics. The default value 1 is the standard engine.

date query · optional · string

Requested snapshot date in YYYY-MM-DD format. When the exact snapshot is unavailable, Google SERP data may come from the nearest earlier snapshot.

Column used to order global Google SERP rankings.

sort_direction query · optional · string · ASC | DESC

Sort in ascending (ASC) or descending (DESC) order using sort_by. Defaults are endpoint-specific when omitted.

page query · optional · integer · default: 1

One-based result page number. Use 1 for the first page.

page_size query · optional · integer · default: 50

Maximum number of items in one page. Public API responses cap this value at 200; some product datasets may apply a lower internal cap.

AI Analytics

AI visibility analytics for GPT-4.1 nano and GPT-5 nano.

GET /ai-analytics/sites

List sites with AI visibility metrics

Returns accessible site records with visibility metrics for the selected public model name. The default model is gpt-5-nano.

limit query · optional · integer · default: 50

Maximum number of site records to return in this cursor page. The API may return fewer records; use has_more and next_cursor to continue.

cursor query · optional · string

Continuation cursor from the previous response meta.next_cursor. Omit it for the first page and treat its value as opaque.

search query · optional · string

Case-insensitive substring matched against the website domain and, when present, its Search Console property URL.

tag_ids query · optional · array<integer>

Comma-separated site tag ids from GET /site-tags. By default a site may match any supplied tag; use tag_match=all to require every tag.

tag_match query · optional · string · any | all · default: any

How tag_ids are combined: any returns a site with at least one selected tag; all requires every selected tag.

exclude_tag_ids query · optional · array<integer>

Comma-separated site tag ids. Sites carrying any excluded tag are omitted.

model query · optional · string · gpt-4.1-nano | gpt-5-nano · default: gpt-5-nano

AI model dataset to query. gpt-4.1-nano selects GPT-4.1 nano analytics; gpt-5-nano selects GPT-5 nano analytics.

site_type query · optional · string · gsc | manual

Return only Search Console-connected records (gsc) or manually added records (manual).

access_type query · optional · string · own | linked | shared

Filter by how this account can access the site: direct ownership, a linked account, or another available account relationship.

GET /ai-analytics/sites/{site_id}/overview

Get AI Analytics overview

Returns AI visibility statistics for the domain resolved from site_id and the selected model.

site_id path · required · integer

Stable site identifier returned by a site collection endpoint.

model query · optional · string · gpt-4.1-nano | gpt-5-nano · default: gpt-5-nano

AI model dataset to query. gpt-4.1-nano selects GPT-4.1 nano analytics; gpt-5-nano selects GPT-5 nano analytics.

GET /ai-analytics/sites/{site_id}/queries

List AI query positions

Returns query, page, position, and category data. query_id and page_id are exact ids returned by this endpoint; position_group provides common TOP filters without constructing arrays.

site_id path · required · integer

Stable site identifier returned by a site collection endpoint.

model query · optional · string · gpt-4.1-nano | gpt-5-nano · default: gpt-5-nano

AI model dataset to query. gpt-4.1-nano selects GPT-4.1 nano analytics; gpt-5-nano selects GPT-5 nano analytics.

position_group query · optional · string · top1 | top3 | top10 | quick_wins

Convenience filter for position sets: top1 is position 1, top3 is 1–3, top10 is 1–10, and quick_wins is 4–10.

query_id query · optional · integer

Exact AI Analytics query id returned by a previous query result.

page_id query · optional · integer

Exact AI Analytics page id returned by a previous result.

sort_by query · optional · string · key_val | page_val | pos | ts · default: pos

Column used to order AI query-position rows.

sort_direction query · optional · string · ASC | DESC

Sort in ascending (ASC) or descending (DESC) order using sort_by. Defaults are endpoint-specific when omitted.

page query · optional · integer · default: 1

One-based result page number. Use 1 for the first page.

page_size query · optional · integer · default: 50

Maximum number of items in one page. Public API responses cap this value at 200; some product datasets may apply a lower internal cap.

GET /ai-analytics/sites/{site_id}/pages

List best AI Analytics pages

Returns best-performing pages for the resolved domain and selected model.

site_id path · required · integer

Stable site identifier returned by a site collection endpoint.

model query · optional · string · gpt-4.1-nano | gpt-5-nano · default: gpt-5-nano

AI model dataset to query. gpt-4.1-nano selects GPT-4.1 nano analytics; gpt-5-nano selects GPT-5 nano analytics.

sort_by query · optional · string · total_queries | avg_pos | share_percent | rating · default: total_queries

Column used to order AI Analytics page rows.

sort_direction query · optional · string · ASC | DESC

Sort in ascending (ASC) or descending (DESC) order using sort_by. Defaults are endpoint-specific when omitted.

page query · optional · integer · default: 1

One-based result page number. Use 1 for the first page.

page_size query · optional · integer · default: 50

Maximum number of items in one page. Public API responses cap this value at 200; some product datasets may apply a lower internal cap.

GET /ai-analytics/sites/{site_id}/competitors

List AI competitors

Returns the leading AI visibility competitors for the resolved domain and selected model.

site_id path · required · integer

Stable site identifier returned by a site collection endpoint.

model query · optional · string · gpt-4.1-nano | gpt-5-nano · default: gpt-5-nano

AI model dataset to query. gpt-4.1-nano selects GPT-4.1 nano analytics; gpt-5-nano selects GPT-5 nano analytics.

GET /ai-analytics/rankings

List global AI visibility rankings

Returns a page of global domain rankings for the selected AI model.

model query · optional · string · gpt-4.1-nano | gpt-5-nano · default: gpt-5-nano

AI model dataset to query. gpt-4.1-nano selects GPT-4.1 nano analytics; gpt-5-nano selects GPT-5 nano analytics.

page query · optional · integer · default: 1

One-based result page number. Use 1 for the first page.

page_size query · optional · integer · default: 50

Maximum number of items in one page. Public API responses cap this value at 200; some product datasets may apply a lower internal cap.

My SEO

Campaign data associated with the authenticated account and an accessible website domain.

GET /my-seo/sites

List sites with campaign data

Returns accessible sites and joins campaign details only when the authenticated account has a campaign for the site domain. Sites without such a campaign have campaign_access=false and campaign=null.

limit query · optional · integer · default: 50

Maximum number of site records to return in this cursor page. The API may return fewer records; use has_more and next_cursor to continue.

cursor query · optional · string

Continuation cursor from the previous response meta.next_cursor. Omit it for the first page and treat its value as opaque.

search query · optional · string

Case-insensitive substring matched against the website domain and, when present, its Search Console property URL.

tag_ids query · optional · array<integer>

Comma-separated site tag ids from GET /site-tags. By default a site may match any supplied tag; use tag_match=all to require every tag.

tag_match query · optional · string · any | all · default: any

How tag_ids are combined: any returns a site with at least one selected tag; all requires every selected tag.

exclude_tag_ids query · optional · array<integer>

Comma-separated site tag ids. Sites carrying any excluded tag are omitted.

site_type query · optional · string · gsc | manual

Return only Search Console-connected records (gsc) or manually added records (manual).

access_type query · optional · string · own | linked | shared

Filter by how this account can access the site: direct ownership, a linked account, or another available account relationship.

has_campaign query · optional · boolean

When true, return only sites with a campaign; when false, return only sites without one.

campaign_status query · optional · string · draft | launched | paused | cancelled

Return only campaigns in this lifecycle state.

campaign_plan query · optional · string · autoseo | fullseo

Return only campaigns using this plan.

GET /my-seo/sites/{site_id}/keywords

List campaign keywords

Available when the authenticated account has a campaign for the site domain. search matches keyword text; target_url is an exact normalized target URL; keyword_group_id restricts results to a reusable group visible for this site.

site_id path · required · integer

Stable site identifier returned by a site collection endpoint.

page query · optional · integer · default: 1

One-based result page number. Use 1 for the first page.

page_size query · optional · integer · default: 50

Maximum number of items in one page. Public API responses cap this value at 200; some product datasets may apply a lower internal cap.

search query · optional · string

Text used to narrow keyword or query results. For Google SERP token search, provide at least four characters.

keyword_group_id query · optional · integer

Restrict results to keywords in this reusable group. Obtain the id from GET /sites/{site_id}/keyword-groups; an empty group returns no matching rows.

source query · optional · string · gsc | serp | manual

Filter campaign keywords by their source.

status query · optional · string · pending | approved | rejected

Filter campaign keywords by review status.

target_url query · optional · string

Exact normalized target URL assigned to a campaign keyword.

Column used to order campaign keywords.

sort_direction query · optional · string · ASC | DESC

Sort in ascending (ASC) or descending (DESC) order using sort_by. Defaults are endpoint-specific when omitted.

POST /my-seo/sites/{site_id}/keywords

Add manual campaign keywords

Adds keyword and target URL pairs to the authenticated account campaign for the site domain when it is a launched FullSEO campaign. Duplicate pairs update the existing manual records. Target URLs must belong to the campaign domain.

Request body application/json one JSON object

Manual keyword rows and their initial review state.

site_id path · required · integer

Stable site identifier returned by a site collection endpoint.

items body · required · array<object>

approved body · optional · boolean · default: true

true saves as Approved; false saves as Recommended.

JSON body example

{
  "items": [
    {
      "keyword": "technical seo audit",
      "url": "https://example.com/seo-audit"
    }
  ],
  "approved": true
}

GET /my-seo/sites/{site_id}/backlinks

List campaign backlinks

Available when the authenticated account has a campaign for the site domain. search matches donor domain, page, question, or associated keyword text.

site_id path · required · integer

Stable site identifier returned by a site collection endpoint.

page query · optional · integer · default: 1

One-based result page number. Use 1 for the first page.

page_size query · optional · integer · default: 50

Maximum number of items in one page. Public API responses cap this value at 200; some product datasets may apply a lower internal cap.

search query · optional · string

Case-insensitive substring matched against donor domain, page, question, and keyword text.

link_type query · optional · string · discussion | article | wiki

Filter backlinks by placement type.

domain_rating query · optional · string · under40 | 40_70 | 70plus

Filter donor domain rating into a simple range: under40, 40_70 (40 inclusive, 70 exclusive), or 70plus.

Column used to order campaign backlinks.

sort_direction query · optional · string · ASC | DESC

Sort in ascending (ASC) or descending (DESC) order using sort_by. Defaults are endpoint-specific when omitted.

Indexing

Indexing URLs owned by the authenticated account.

GET /indexing/urls

List indexing URLs

Returns indexing URLs and their current crawler status for the authenticated account. url_contains and domain are independent, case-insensitive substring filters.

page query · optional · integer · default: 1

One-based result page number. Use 1 for the first page.

page_size query · optional · integer · default: 50

Maximum number of items in one page. Public API responses cap this value at 200; some product datasets may apply a lower internal cap.

url_contains query · optional · string

Case-insensitive substring matched against the complete submitted URL.

domain query · optional · string

Domain or hostname substring. A supplied URL is normalized to its domain before filtering.

status query · optional · string · queued | processing | visited | failed

Filter by readable indexing state.

bot query · optional · string · google | openai | bing

Filter by crawler that processes the URL.

sort_by query · optional · string · url | domain | bot | status | created · default: created

Column used to order indexing records.

sort_direction query · optional · string · ASC | DESC

Sort in ascending (ASC) or descending (DESC) order using sort_by. Defaults are endpoint-specific when omitted.

POST /indexing/urls

Add URLs to indexing

Submits each unique URL for every selected bot and debits the account indexing balance only for persisted requests. google is the default bot; bing is also supported. This operation does not accept an idempotency key: after an ambiguous network failure, inspect GET /indexing/urls before retrying.

Request body application/json one JSON object

Complete URLs and supported crawler names.

urls body · required · array<string>

bots body · optional · array<string> · default: google

JSON body example

{
  "urls": [
    "https://example.com/",
    "https://example.com/page"
  ],
  "bots": [
    "google"
  ]
}

Errors

Errors use application/problem+json. The stable code is suitable for application logic; include request_id when contacting support.

{
  "type": "https://semalt.com/api-docs#errors",
  "title": "Unauthorized",
  "status": 401,
  "code": "invalid_api_key",
  "detail": "The API key is invalid or inactive.",
  "request_id": "..."
}