API
API / Project API / Project Management

Project Management

You are reading the Project API docs

Base URL: api4.seranking.com

Project API uses subscription limits. Fro more information visit API credit system.

Data API and Project API keys are not interchangeable — use the correct one to avoid authentication errors.

Data apikey example:
80cfee7d-xxxx-xxxx-xxxx-fc8500816bb3
(UUID format)
Project apikey example:
253a73adxxxxxxxxxxxxxx340aa0a939
(40-char hex)
API dashboard

API keys are available in your account. For any questions or 401 errors, email [email protected] for support.

Project Management API provides endpoints to manage projects and retrieve ranking-related data.

It allows you to:

  • create, update, and delete projects
  • configure search engines for a project
  • add, update, and delete project keywords
  • retrieve keyword rankings and historical data
  • access project-level summary statistics
  • trigger manual ranking checks
  • manage manual ranking positions
  • retrieve advertising and SERP feature statistics

List projects

GET https://api4.seranking.com/sites

Returns a list of all projects available in the user account.

Request format

Copy
GET https://api4.seranking.com/sites

Response parameters

ParameterTypeDescription
idIntegerUnique project (site) ID.
titleStringProject name.
nameStringWebsite URL associated with the project.
group_idIntegerProject group ID.
is_activeIntegerProject status:
• 1 – active
• 0 – delayed
exact_urlIntegerIf 1, ranking positions are checked only for the specified URL, excluding subfolders and subdomains.
subdomain_matchIntegerIf 1, SERP subdomains are taken into account.
depthIntegerRanking position collection depth.
check_freqStringFrequency of ranking checks.
check_dayInteger• If check_freq is check_weekly, represents the day of the week (1 – Monday to 7 – Sunday).
• If check_freq is check_monthly, represents the day of the month (1 – 31).
guest_linkStringGuest link to view project statistics without authorization.
keyword_countIntegerNumber of keywords added to the project.

Response example

Copy
[

  {

    "id": 1,

    "title": "zniqpf tfallp mykqeg",

    "name": "Cronin.info",

    "group_id": 0,

    "is_active": 1,

    "exact_url": 0,

    "subdomain_match": 0,

    "depth": 100,

    "check_freq": "check_daily",

    "check_day": null,

    "guest_link": "https://seranking.com/guest.html?site_id=1&hv=0&hash=432&tab=detailed"

  }

]

List project search engines

GET https://api4.seranking.com/sites/{site_id}/search-engines

Returns a list of search engines configured for the specified project.

Request format

Copy
GET https://api4.seranking.com/sites/{site_id}/search-engines

Response parameters

If successful, the server returns the 200 HTTP code and a JSON array of search engines associated with the project. If an error occurs (e.g., unknown search_engine_id or site_engine_id), the API returns the corresponding HTTP status code and error message. See Error handling for possible error codes.

ParameterTypeDescription
site_engine_idIntegerUnique ID of the search engine configuration within the project.
search_engine_idIntegerSearch engine ID (refer to /system/search-engines).
region_idIntegerRegion ID.
region_nameStringRegion name. Only applicable to Google.
lang_codeStringLanguage code (refer to /system/google-langs).
merge_mapIntegerGoogle Maps SERPs handling mode:
• 0 – don’t include
• 1 – include
• 2 – include and display separately
business_nameStringBusiness name used for Google Maps SERPs.
phoneStringCompany phone number used for Google Maps SERPs.
paid_resultsIntegerTrack rankings in Google Ads: 1 – yes, 0 – no.
featured_snippetIntegerTrack Featured Snippet results:
• 1 – include
• 0 – exclude
keyword_countIntegerNumber of keywords assigned to this search engine configuration.

Response example

Copy
[

  {

    "site_engine_id": 1,

    "search_engine_id": 339,

    "region_id": 0,

    "region_name": null,

    "lang_code": "ru",

    "merge_map": 0,

    "business_name": null,

    "phone": null,

    "paid_results": 0,

    "featured_snippet": 0,

    "keyword_count": 10

  }

]

Add search engine to project

POST https://api4.seranking.com/sites/{site_id}/search-engines

Adds a new search engine configuration to the specified project.

Request parameters

ParameterTypeRequiredDescription
site_idIntegerYesUnique project (site) ID.
search_engine_idIntegerYesSearch engine ID (refer to /system/search-engines).
region_idIntegerNoRegion ID.
region_nameStringNoGeographical name (region or city) in English. Only applicable to Google.
lang_codeStringNoLanguage code (refer to /system/google-langs).
merge_mapIntegerNoGoogle Maps SERPs handling mode:
• 0 – don’t include
• 1 – include
• 2 – include and display separately
business_nameStringNoBusiness name for Google Maps SERPs.
phoneStringNoCompany phone number for Google Maps SERPs.
paid_resultsIntegerNoTrack rankings in Google Ads: 1 – yes, 0 – no.
featured_snippetIntegerNoTrack Featured Snippet results:
• 1 – include
• 0 – exclude

Request example

Copy
POST https://api4.seranking.com/sites/{site_id}/search-engines

{

  "search_engine_id": 339,

  "region_id": 0,

  "region_name": null,

  "lang_code": "ru",

  "merge_map": 0,

  "business_name": null,

  "phone": null,

  "paid_results": 0,

  "featured_snippet": 0

}

Response parameters

If successful, the server returns the 201 HTTP code and the site_engine_id of the newly added search engine configuration. If an error occurs (e.g., unknown search_engine_id), the API returns the corresponding HTTP status code and error message (for more information, see Error handling).

Change search engine in project

PUT https://api4.seranking.com/sites/{site_id}/search-engines/{site_engine_id}

Updates an existing search engine configuration for the specified project.

Request parameters

ParameterTypeRequiredDescription
site_idIntegerYesUnique project (site) ID.
site_engine_idIntegerYesUnique ID of the search engine configuration within the project.
region_idIntegerNoRegion ID.
region_nameStringNoGeographical name (region or city) in English. Only applicable to Google.
lang_codeStringNoLanguage code (refer to /system/google-langs).
merge_mapIntegerNoGoogle Maps SERPs handling mode:
• 0 – don’t include
• 1 – include
• 2 – include and display separately
business_nameStringNoBusiness name for Google Maps SERPs.
phoneStringNoCompany phone number for Google Maps SERPs.
paid_resultsIntegerNoTrack rankings in Google Ads: 1 – yes, 0 – no.
featured_snippetIntegerNoTrack Featured Snippet results:
• 1 – include
• 0 – exclude

Request example

Copy
PUT https://api4.seranking.com/sites/{site_id}/search-engines/{site_engine_id}

{

  "region_id": 0,

  "region_name": null,

  "lang_code": "ru",

  "merge_map": 0,

  "business_name": null,

  "phone": null,

  "paid_results": 0,

  "featured_snippet": 0

}

Response parameters

If successful, the server returns the 200 HTTP code. If an error occurs (e.g., unknown site_engine_id), the API returns the corresponding HTTP status code and error message (for more information, see Error handling).

Delete search engine from project

DELETE https://api4.seranking.com/sites/{site_id}/search-engines/{site_engine_id}

Removes a search engine configuration from the specified project.

Request parameters

ParameterTypeRequiredDescription
site_idIntegerYesUnique project (site) ID.
site_engine_idIntegerYesUnique ID of the search engine configuration within the project.

Request example

Copy
DELETE https://api4.seranking.com/sites/{site_id}/search-engines/{site_engine_id}

Response parameters

If successful, the server returns the 204 HTTP code. If an error occurs, the API returns the corresponding HTTP status code and error message (for more information, see Error handling).

List website keywords

GET https://api4.seranking.com/sites/{site_id}/keywords

Returns a list of keywords for the specified project, including their assigned target URLs and basic statistics.

Request parameters

ParameterTypeRequiredDescription
site_idIntegerYesUnique project (site) ID.
site_engine_id  IntegerNoUnique ID of the search engine configuration within the project. If provided, first_check_date is returned.

Request example

Copy
GET https://api4.seranking.com/sites/{site_id}/keywords?site_engine_id=NNN

Response parameters

If successful, the server returns the 200 HTTP code and a JSON array of project keywords. If an error occurs, the API returns the corresponding HTTP status code and error message (for more information, see Error handling).

ParameterTypeDescription
idStringUnique keyword ID.
nameStringKeyword text.
group_idStringKeyword group ID.
linkStringTarget URL assigned to the keyword.
first_check_dateStringDate of the first ranking check (YYYY-MM-DD).
tagsArrayList of tag IDs assigned to the keyword.
site_engine_idsArrayList of associated search engine configuration IDs.

Response example

Copy
[

  {

    "id": "1",

    "name": "key1",

    "group_id": "2",

    "link": null,

    "first_check_date": "2015-02-17"

  },

  {       

    "id": "2",      

    "name": "key2",    

    "group_id": "2",     

    "link": "http://mysite.com/",    

    "first_check_date": null,    

    "tags": [] 

  },

  ...

]

Get project summary statistics

GET https://api4.seranking.com/sites/{site_id}/stat

Returns summary statistics for the specified project.

Request parameters

ParameterTypeRequiredDescription
site_idIntegerYesUnique project (site) ID.

Request example

Copy
GET https://api4.seranking.com/sites/{site_id}/stat

Response parameters

If successful, the server returns HTTP 200 and a JSON object containing summary metrics.

ParameterTypeDescription
site_idIntegerUnique website ID.
nameStringWebsite domain.
group_idIntegerProject group ID.
titleStringProject title.
today_avgNumberAverage position for the latest ranking check date.
yesterday_avgNumberAverage position for the previous ranking check date.
total_upIntegerTotal number of positions that improved in SERPs.
total_downIntegerTotal number of positions that declined in SERPs.
processStringPercentage of processed website positions.
top5IntegerNumber of keywords ranking in the top 5.
top10IntegerNumber of keywords ranking in the top 10.
top30IntegerNumber of keywords ranking in the top 30.
visibilityNumberTraffic forecast value.
visibility_percentNumberVisibility percentage.
daNumberMoz Domain Authority.
index_googleIntegerNumber of pages indexed in Google.

Response example

Copy
{

  "site_id": 123,

  "name": "site1.com",

  "group_id": null,

  "title": "my site",

  "today_avg": 123,

  "yesterday_avg": 111,

  "total_up": 0,

  "total_down": 5,

  "process": "99.9",

  "top5" : 1,

  "top10" : 2,

  "top30" : 3,

  "visibility" : 2,

  "visibility_percent" : 30.0,

  "da" : 4,

  "index_google" : 200,

  "index_x" : null

}

Get keyword statistics

GET https://api4.seranking.com/sites/{site_id}/positions

Returns keyword ranking statistics for the specified project within a selected time period.

Request parameters

ParameterTypeRequiredDescription
site_idIntegerYesUnique project (site) ID.
date_fromStringNoStart date of the time period (YYYY-MM-DD). The default is today minus one week.
date_toStringNoEnd date of the time period (YYYY-MM-DD). The default is today.
site_engine_idIntegerNoSearch engine configuration ID. If not specified, data for all search engines is returned.
in_topIntegerNoFilter by ranking position. Example: in_top=10 returns keywords ranking in the TOP 10 at the last check date within the selected period.
with_landing_pagesIntegerNoLanding page URLs found in SERPs (1 – include).
with_serp_featuresIntegerNoDetected Google SERP features (1 – include).

Request example

Copy
GET https://api4.seranking.com/sites/{site_id}/positions?date_from=2018-01-01&date_to=2018-01-07&site_engine_id=1&with_landing_pages=1&with_serp_features=1

Response parameters

If successful, the server returns a JSON array grouped by site_engine_id, containing keyword statistics for the specified period. If an error occurs (e.g., invalid site_engine_id), the API returns the corresponding HTTP status code and error message (for more information, see Error handling).

ParameterTypeDescription
site_engine_idIntegerSearch engine configuration ID.
keywordsArrayList of keywords with statistics.

Each object in the keywords array has the following structure:

ParameterTypeDescription
idStringUnique keyword ID.
positionsArrayRanking positions by date.
volumeIntegerSearch volume.
competitionNumberCompetition level.
suggested_bidNumberEstimated cost per click.
keiNumberKeyword Efficiency Index.
resultsIntegerNumber of search results in Google.
total_sumNumberPrice per keyword (based on financial report settings).
landing_pagesArrayLanding page data:
date – ranking check date (YYYY-MM-DD)
url – page URL in SERPs for the keyword
featuresObjectDetected SERP features. Each field is true if the feature links to the project’s website; otherwise false.

Each object in the positions array has the following structure:

ParameterTypeDescription
dateStringDate (YYYY-MM-DD).
posIntegerCurrent ranking position.
changeIntegerChange in position compared to the previous date (could be negative).
priceNumberPrice calculated from financial report settings.
is_mapIntegerResults where the position was found:
• 0 – organic search results
• 1 – maps block
map_positionNumberPosition in the maps block when merge_map is 2 (i.e., “Display organic and maps results separately” is enabled).
paid_positionNumberPosition in paid Google SERPs.

Response example

Copy
[

  {

    "site_engine_id": 1,

    "keywords": [

      {

        "id": "12",

        "positions": [

          {

            "date": "2017-12-19",

            "pos": 18,

            "change": 0,

            "price": 0,

            "is_map": 0,

            "map_position": 0,

            "paid_position": 0

          }

        ],

        "volume": 390,       

        "competition": 3,         

        "suggested_bid": 1,    

        "kei": 1,    

        "results": 100,     

        "total_sum": 0,

        "landing_pages": [

          {

            "url": "https://domain.com/page.html",

            "date": "2017-12-14"

          }

        ],

        "features": {

          "tads": true,

          "knowledge_graph": true,

          "images": true,

          "sitelinks": true,

          "reviews": false

        }

      },  

   ...

]

Get total number of ads chart

GET https://api4.seranking.com/sites/{site_id}/ads

Returns the total number of top and bottom advertisements in search results by date for the specified project. Data can be filtered by search engines, keywords, and date range.

Request parameters

All parameters are query parameters.

ParameterTypeRequiredDescription
date_fromStringNoStart date of the period (YYYY-MM-DD format). Defaults to today minus one week.
date_toStringNoEnd date of the period (YYYY-MM-DD format). Defaults to today.
site_engine_idsArrayNoSearch engine ID filter. If not specified, data for all search engines is returned.
keywords_idsArrayNoKeyword ID filter. If not specified, data for all keywords is returned.

Request example

Copy
GET https://api4.seranking.com/sites/{site_id}/ads?date_from=2020-05-20&date_to=2020-05-21&site_engine_ids[]=1&site_engine_ids[]=2&keywords_ids[]=1&keywords_ids[]=1

Response parameters

If successful, the server returns the HTTP 200 code and an array grouped by site_engine_id. A maximum of 100,000 records is returned.

ParameterTypeDescription
site_engine_idIntegerSearch engine configuration ID.
keywordsArrayArray of keywords with advertisement statistics.

Each keywords object has the following structure:

ParameterTypeDescription
idIntegerKeyword ID.
adsArrayDaily advertisement statistics.

Each ads object has the following structure:

ParameterTypeDescription
dateStringDate (in YYYY-MM-DD).
tadsIntegerTotal number of top ads.
badsIntegerTotal number of bottom ads.

Response example

Copy
[

  {

    "site_engine_id": 1,

    "keywords": [

      {

        "id": 1,

        "ads": [

          {

            "date": "2020-05-20",

            "tads": 2,

            "bads": 3

          },

          {

            "date": "2020-05-21",

            "tads": 3,

            "bads": 2

          }

        ]

      },

      {

        "id": 2,

        "ads": [

          {

            "date": "2020-05-20",

            "tads": 0,

            "bads": 0

          },

          {

            "date": "2020-05-21",

            "tads": 0,

            "bads": 1

          }

        ]

      }

    ]

  },

  {

    "site_engine_id": 2,

    "keywords": [

      {

        "id": 1,

        "ads": [

          {

            "date": "2020-05-20",

            "tads": 1,

            "bads": 1

          },

          {

            "date": "2020-05-21",

            "tads": 2,

            "bads": 2

          }

        ]

      },

      {

        "id": 2,

        "ads": [

          {

            "date": "2020-05-20",

            "tads": 0,

            "bads": 2

          },

          {

            "date": "2020-05-21",

            "tads": 5,

            "bads": 1

          }

        ]

      }

    ]

  }

]

Get historical dates

GET https://api4.seranking.com/sites/{site_id}/historicalDates

Returns a list of historical dates used to build ranking position comparison charts for the specified project.

The following logical periods are supported:

  • current
  • day_ago
  • 7days
  • 30days
  • 90days
  • 180days
  • first

If no ranking check occurred on a specific date, the closest available check date is returned.

Request parameters

ParameterTypeRequiredDescription
site_engine_idIntegerNoSearch engine configuration ID. If omitted, dates are returned for all search engines.

Request example

Copy
GET https://api4.seranking.com/sites/{site_id}/historicalDates

Response parameters

If successful, the server returns the HTTP 200 code and an object containing date mappings.

ParameterTypeDescription
currentStringCurrent check date (in YYYY-MM-DD).
day_agoStringClosest date to one day ago.
7daysStringClosest date to seven days ago.
30daysStringClosest date to thirty days ago.
90daysStringClosest date to ninety days ago.
180daysStringClosest date to one hundred eighty days ago.
firstStringFirst available ranking check date.

Response example

Copy
{ "current" : "2019-02-20", "day_ago" : "2019-02-19", "7days" : "2019-02-14"}

Add keywords to project

POST https://api4.seranking.com/sites/{site_id}/keywords

Adds new keywords to the specified project.

Request parameters

ParameterTypeRequiredDescription
keywordStringYesKeyword text.
group_idIntegerNoKeyword group ID. If omitted, the default group is used.
target_urlStringNoTarget URL assigned to the keyword.
is_strictIntegerNoCheck positions only for the specified target URL (1 – yes, 0 – no). Defaults to 0.
commentStringNoComment for the keyword.
site_engine_idsArrayNoArray of search engine IDs where the keyword should be tracked.

Request example

Copy
POST https://api4.seranking.com/sites/{site_id}/keywords

[

  {

    "keyword":"text",

    "group_id":1,

    "target_url": "http://site.com/",

    "is_strict": 0,

    "comment":"text",

    "site_engine_ids": [20,21]

  }

]

Response parameters

If successful, the server returns an object containing the number of added keywords. Returns HTTP 400 if no keywords are specified (for more information, see Error handling).

ParameterTypeDescription
addedIntegerNumber of successfully added queries to the project.
idsArrayArray of IDs of added keywords.

Response example

Copy
{

    "added": 3,

    "ids": [123, 456, 789]

}

Add project

POST https://api4.seranking.com/sites

Creates a new project in the user account.

Request parameters

ParameterTypeRequiredDescription
urlStringYesWebsite URL.
titleStringYesProject name.
depthIntegerNoRanking collection depth (100, 200). Defaults to 100.
subdomain_matchIntegerNoInclude subdomains in SERPs (1 – yes, 0 – no). Defaults to 0.
exact_urlIntegerNoTrack only the specified URL (1 – yes, 0 – no). Defaults to 0.
check_freqStringNoCheck frequency (check_daily, check_1in3, check_weekly, check_monthly, manual). Defaults to check_daily.
auto_reportsIntegerNoEnable weekly reports (1 – yes, 0 – no). Defaults to 1.
disable_auditIntegerNoDisable website audit (1 – yes, 0 – no). Defaults to 0.
site_group_idIntegerNoProject group ID.
check_dayIntegerNoDay of week (1–7) for weekly checks or day of month (1–31) for monthly checks.
is_activeIntegerNoProject status (1 – active, 0 – delayed).

Request example

Copy
POST https://api4.seranking.com/sites

[{"url": "http://test.site/","title": "seo site"}]

Response parameters

If successful, the server returns the 201 HTTP code and the ID of the project added to the account.

ParameterTypeDescription
site_idIntegerID of the created project.

Response example

Copy
{ "site_id": 507052 }

Change project settings

PUT https://api4.seranking.com/sites/{site_id}

Updates the settings of the specified project.

Request parameters

ParameterTypeRequiredDescription
urlStringNoWebsite URL.
titleStringNoProject name.
depthIntegerNoRanking collection depth (100, 200). Defaults to 100.
subdomain_matchIntegerNoInclude subdomains in SERPs (1 – yes, 0 – no). Defaults to 0.
exact_urlIntegerNoTrack only the specified URL (1 – yes, 0 – no). Defaults to 0.
check_freqStringNoCheck frequency (check_daily, check_1in3, check_weekly, check_monthly, manual). Defaults to check_daily.
site_group_idIntegerNoProject group ID.
check_dayIntegerNoDay of week (1–7) for weekly checks or day of month (1–31) for monthly checks.
is_activeIntegerNoProject status (1 – active, 0 – delayed).

Request example

Copy
PUT https://api4.seranking.com/sites/{site_id}

{

  "title": "new site title"

}

Response parameters

If successful, the server returns the 200 HTTP code.

Response example

No response body.

Delete project

DELETE https://api4.seranking.com/sites/{site_id}

Deletes the specified project from the user account.

Request parameters

Path parameter:

ParameterTypeRequiredDescription
site_idIntegerYesUnique project (site) ID.

Request example

Copy
DELETE https://api4.seranking.com/sites/{site_id}

Response parameters

If successful, the server returns the 204 HTTP code.

Response example

No response body.

Delete keywords

DELETE https://api4.seranking.com/sites/{site_id}/keywords

Deletes keywords from the specified project.

Request parameters

ParameterTypeRequiredDescription
keywords_idsArrayYesArray of keyword IDs to delete.

Request example

Copy
DELETE https://api4.seranking.com/sites/{site_id}/keywords?keywords_ids[]=1&keywords_ids[]=2&keywords_ids[]=3

Response parameters

If successful, the server returns the 204 HTTP code. Returns HTTP 400 if no keyword IDs are specified (for more information, see Error handling).

Response example

No response body.

Set manual keyword position

PUT https://api4.seranking.com/sites/{site_id}/position

Sets a ranking position for a project keyword on a specified date.

Request parameters

ParameterTypeRequiredDescription
keyword_idIntegerYesUnique keyword ID (refer to https://api4.seranking.com/sites/{site_id}/keywords).
dateStringYesDate of the ranking record.
site_engine_idIntegerYesSearch engine configuration ID (refer to https://api4.seranking.com/sites/{site_id}/search-engines).
positionIntegerYesPosition (0 – 200). 0 – means “not found”.

Request example

Copy
PUT https://api4.seranking.com/sites/{site_id}/position/

{"keyword_id": 1,"date": "2018-01-01","position":100,"site_engine_id": 1}

Response parameters

If successful, the server returns the 200 HTTP code.

Returns HTTP 400 for:

  • invalid date
  • invalid keyword_id
  • unknown site_engine_id

Response example

No response body.

Run position check

POST https://api4.seranking.com/api/sites/{site_id}/recheck

Triggers a ranking position check for selected keywords or for an entire project.

Request parameters

ParameterTypeRequiredDescription
site_engine_idIntegerNoSearch engine configuration ID. If provided without keywords, runs a check for all keywords within that search engine.
keywordsArrayYes*List of keyword objects to recheck. If provided, site_engine_id is ignored.

Each keywords object has the following structure:

ParameterTypeRequiredDescription
site_engine_idIntegerYesSearch engine configuration ID.
keyword_idIntegerYesKeyword ID.

* Required unless site_engine_id alone is used to recheck all keywords for that search engine.

Request example

Copy
POST https://api4.seranking.com/api/sites/{site_id}/recheck/

{ "keywords":[ {"site_engine_id":1, "keyword_id":2} ]}

Response parameters

If successful, the server returns the number of keywords scheduled for recheck. Returns HTTP 400 if an unknown site_engine_id is provided (for more information, see Error handling).

ParameterTypeRequiredDescription
totalIntegerYesNumber of keywords for which the position check was launched.

Response example

Copy
{ "total": 5 }

Learn how SE Ranking’s API can boost your SEO!

Hi! Meet our product expert, Alex.

He’ll walk you through the API and show you how to get the most out of it.

  • Enjoy a tailored demo on integrating rich, structured SEO data into your stack.
  • Pin down every tech detail live—auth, endpoints, rate limits, data formats.
  • Compare usage tiers and pricing so you can unlock maximum data value.

Request a free demo to see our tools and integrations in action

By clicking this button, you agree to SE Ranking’s Terms of Services and Privacy Policy.