Premium API

Using the API

Welcome to the Siteliner Premium API for developers.

This API (Application Programming Interface) allows your developers to write scripts on your server that control Siteliner Premium scans and retrieve their results in JSON format.

Each scan initiated using the API is billed in the same way as an operation performed through the web-based Siteliner Premium service, costing 1c per page scanned. Each API request to retrieve a scan's results also costs 1c. API requests to control scans and retrieve account details are free.

Usage of the API and web-based interface can be mixed. The results of scans initiated via the API can be browsed online freely, and the API can be used to retrieve the results of scans initiated via the web.

Reports are available for 6 months after the scan was started.

Sample Code

Click to download sample code for accessing the Siteliner API in PHP and Python.

Account Summary Report

Request and Response

To retrieve a list of completed and running scans and account balance, send an HTTP GET request to this URL:

https://www.siteliner.com/api

Usage of this API command is free. Parameters are specified on the URL (using ? and &) as follows:

Parameter Explanation Value Required? Default
user Your username Yes
key Your API key Yes
report Report requested account Yes
count Maximum number of results 1 - 100 No 100
start Index of first result (results are ordered chronologically by scan start time, with the most recent first) 1 or greater No 1


The API returns a JSON object containing the following elements:

Element Explanation Example
report Provided report parameter account
value Account balance in dollars 999.50
credits Account balance in 1c credits 99950
resultcount Total results available for this report (ignoring count and start parameters) 31
results Array of result objects, details below


Each object in the results array may contain the following subelements:

Element Explanation Example
scan Scan ID for use in other API requests lmjib545ec
rooturl Initial URL of scan http://www.example.com/
viewurl URL for viewing this scan online https://www.siteliner.com/lmjib545ec
status One of: running, paused, stopping, stopped, completed completed
starttime Scan start time as Unix timestamp 1585649722
endtime Scan end time, If scan stopped or completed 1585649742
scancost Cost of scan so far, in dollars 9.50
apicost Cost of API requests retrieving scan results so far 4.27
found Number of pages found so far 25
retrieved Number of pages retrieved so far 16


Example API request to retrieve your account summary:

Scan Management APIs

Start Scan Request

To start a new scan, send an HTTP POST request to this URL:

https://www.siteliner.com/api

Usage of this API command is free, but your account will be charged 1c per page for the scan itself. Parameters can be specified on the URL or using form urlencoding (see below). The following parameters are required:

Parameter Explanation Value Required?
user Your username Yes
key Your API key Yes
command API command start Yes
rooturl Initial URL for scan [urlencoded URL] Yes
maxpages Maximum number of pages to retrieve 1 - 25000 Yes


The following optional parameters are also available:

Parameter Explanation Value Required? Default
threads Maximum number of pages to retrieve simultaneously 1 - 4 No 4
scanmode Control which pages are scanned One of: normal, all, excludedir, rooturl, customrobotstxt (see table below) No normal
includenofollow Include pages where all inward links are "nofollow" help 1 or 0 No 0
ignorerobotstags Ignore robots meta tags help 1 or 0 No 0
excludedirs Exclude specific directories [list of excluded directories in website, separated by newlines, e.g. sports/\nbusiness/banking/] if scanmode = excludedir
customrobotstxt Custom robots.txt file [robots.txt rows, separated by newlines] if scanmode = customrobotstxt
usesitemap Include pages from sitemaphelp 1 or 0 No 0


The scanmode parameter can take the following values:

Value Explanation
normal Scan all pages on the domain of the rooturl, respecting the robots.txt file if found (default).
all Scan all pages on the domain of the rooturl, ignoring the robots.txt file.
excludedirs Scan all pages on the domain of the rooturl, but exclude specific directories (see excludedirs parameter) and ignore robots.txt. help
customrobotstxt Scan all pages on the domain of the rooturl, and apply a custom robots.txt file (see customrobotstxt parameter). help
rooturl Only scan files within the rooturl directory and ignore robots.txt. help


Each parameter can be specified in one of two ways:

  • Form Encoded. Provide the parameter value as form-urlencoded data within the HTTP POST payload. This is how web browsers submit forms over HTTP, and will usually be easiest. If your scripting language lets you create an HTTP POST request with a list of parameter values, it will probably build this automatically.
  • Via URL. Provide the parameter value on the URL (using urlencoding and ? and &, as with HTTP GET). This method may be easier if you are building HTTP requests at a lower level, or using a command-line tool such as curl. Normally, this method cannot be used for excludedirs and customrobotstxt parameters.

If a parameter is specified several times, the last value is used, with Form Encoded overriding Via URL.

The API returns a JSON object described in Scan Management Response below.

Pause Scan Request

To pause a scan, send an HTTP POST request to this URL:

https://www.siteliner.com/api

Usage of this API command is free. Parameters are specified on the URL (using ? and &) as follows:

Parameter Explanation Value Required?
user Your username Yes
key Your API key Yes
command API command pause Yes
scan Scan ID (from scan field of other API responses) [Scan ID] Yes

The API returns a JSON object described in Scan Management Response below.

Resume Scan Request

To resume a paused scan, send an HTTP POST request to this URL:

https://www.siteliner.com/api

Usage of this API command is free, but your account will be charged 1c per page for the scan itself. Parameters are specified on the URL (using ? and &) as follows:

Parameter Explanation Value Required?
user Your username Yes
key Your API key Yes
command API command resume Yes
scan Scan ID (from scan field of other API responses) [Scan ID] Yes

The API returns a JSON object described in Scan Management Response below.

Cancel Scan Request

To cancel a scan, send an HTTP POST request to this URL:

https://www.siteliner.com/api

Usage of this API command is free. Parameters are specified on the URL (using ? and &) as follows:

Parameter Explanation Value Required?
user Your username Yes
key Your API key Yes
command API command cancel Yes
scan Scan ID as returned by 'Start Scan' API, (field scan) [Scan ID] Yes

The API returns a JSON object described in Scan Management Response below.

Check Scan Status Request

To check the status of a scan, send an HTTP GET request to this URL:

https://www.siteliner.com/api

Usage of this API command is free. Parameters are specified on the URL (using ? and &) as follows:

Parameter Explanation Value Required?
user Your username Yes
key Your API key Yes
report Report requested status Yes
scan Scan ID (from scan field of other API responses) [Scan ID] Yes


Example API request to check the status of scan lmjib545ec: The API returns a JSON object described in Scan Management Response below.

Scan Management Response

All scan management APIs return a JSON object containing the following elements:

Element Explanation Present? Example
scan Scan ID If scan exists lmjib545ec
rooturl Initial URL of scan If scan exists https://www.example.com
report Provided report or command parameter Yes status
viewurl URL for viewing this scan online If scan exists https://www.siteliner.com/lmjib545ec
status One of: running, paused, stopping, stopped, completed If scan exists completed
starttime Scan start time as Unix timestamp If scan exists 1585649722
endtime Scan end time If stopped or completed 1585649742
scancost Cost of scan so far, in dollars If succeded 9.50
apicost Cost of API requests retrieving scan results so far If succeded 4.27
found Number of pages found so far If succeded 25
retrieved Number of pages retrieved so far If succeded 16
error Error message On failure Server not found - please check that you entered the URL correctly.

Scan Summary Report

Request and Response

To retrieve the summary of scan's results, send an HTTP GET request to this URL:

https://www.siteliner.com/api

This API request costs 1c. The scan summary is available for 6 months after the scan was started. Parameters are specified on the URL (using ? and &) as follows:

Parameter Explanation Value Required?
user Your username Yes
key Your API key Yes
report Report requested sitesummary Yes
scan Scan ID (from scan field of other API responses) [Scan ID] Yes


The Scan Summary request returns a JSON object containing the following elements:

Element Explanation Example
scan Scan ID lmjib545ec
rooturl Initial URL of scan https://www.example.com
report Provided report parameter sitesummary
viewurl URL for viewing this scan online https://www.siteliner.com/lmjib545ec?siteliner=site-dashboard
status One of: running, paused, stopping, stopped, completed completed
starttime Scan start time as Unix timestamp 1585649722
endtime Scan end time 1585649742
scancost Cost of scan, in dollars 9.50
apicost Cost of API requests retrieving scan results so far 4.27
found Number of pages found (total of retrieved, disallowed, nofollowed and limitreached) 25
retrieved Number of pages retrieved (total of analyzed, redirected, noindexed, notsupported and failed) 16
disallowed Number of pages not retrieved due to robots.txt or scan options 2
nofollowed Number of pages not retrieved due to all "nofollow" inwards links 0
limitreached Number of pages not retrieved due to scan page limit or scan being stopped 4
issues Array of strings describing site issues found by Siteliner (see online summary report for details)
analyzed Number of pages retrieved whose content was analyzed 16
redirected Number of pages retrieved but which redirected to a different URL 3
noindexed Number of pages retrieved but ignored due a "noindex" robots meta tag 0
notsupported Number of pages retrieved but not supported (e.g. PDFs) 3
failed Number of pages which could not be retrieved due to an error 2
duplicate Percent of duplicate content across all pages 29.5
common Percent of common content across all pages (see FAQs) 12.3
unique Percent of unique content across all pages 58.2
brokenpages Number of pages with broken internal links 3
brokenlinks Number of broken internal links found 7
totallinks Total number of internal links 60
error Error message (only present if an error occurred) Scan not found.


Example API request to retrieve the summary of scan lmjib545ec:

Site Reports

Request and Response

To retrieve a site report for a completed or stopped scan, send an HTTP GET request to this URL:

https://www.siteliner.com/api

Each API request for a site report costs 1c. Site reports are available for 6 months after the scan was started. Parameters are specified on the URL (using ? and &) as follows:

Parameter Explanation Value Required? Default
user Your username Yes
key Your API key Yes
report Report requested One of: siteanalyzed, siteskipped, siteduplicate, sitebroken, siterelateddomain Yes
scan Scan ID (from scan field of other API responses) [Scan ID] Yes
count Maximum number of results 1 - 100 No 100
start Index of first result to return (see each report's details for ordering) 1 or greater No 1


These APIs return a JSON object containing the following elements:

Element Explanation Example
scan Scan ID lmjib545ec
rooturl Initial URL of scan https://www.example.com/
report Provided report parameter siteanalyzed
viewurl URL for viewing this report online https://www.siteliner.com/lmjib545ec?siteliner=site-overview
resultcount Total results available for this report (ignoring count and start parameters) 31
results Array of result objects, see each report's details below
error Error message (only present if an error occurred) Scan not found.


Example API request to retrieve Analyzed Pages report of scan lmjib545ec:

Analyzed Pages Results

The siteanalyzed report lists the pages whose content was analyzed during the scan. Each object in the results array may contain the following subelements:

Element Explanation Example
page Address of page within domain path/page.html
url Full URL of page http://www.example.com/path/page.html
viewurl URL for viewing cached copy of this page (available up to 30 days from scan start) https://www.siteliner.com/lmjib545ec/path/page.html?siteliner=cached
title Title of page if available News
inlinks Number of pages found with internal links to this page ("nofollow" links excluded) 4
power Page power (see FAQs) 94
size Size of page HTML in bytes 9378
words Number of words on page 443
modified Time page was last modified according to HTTP headers, as Unix timestamp 1588496264

For the Analyzed Pages report, the results array is ordered alphabetically by page.

Skipped Pages Results

The siteskipped report lists pages which were found, but whose content was not analyzed during the scan. Each object in the results array may contain the following subelements:

Element Explanation Example
page Address of page within domain path/page.html
url Full URL of page http://www.example.com/path/page.html
viewurl URL for viewing information about this page online (available up to 6 months from scan start) https://www.siteliner.com/lmjib545ec/path/page.html?siteliner=page-linkin
inlinks Number of pages found with internal links to this page ("nofollow" links included only if reason is nofollowed) 4
power Page power (see FAQs) 94
reason Reason for skipping page. One of: disallowed, nofollowed, limitreached, redirectcanonical, redirectframe, redirectheader, redirecttag, noindexed, notsupported, failed (see corresponding elements in Scan Summary response for explanations). disallowed
target Redirection target (if reason is redirectcanonical, redirectframe, redirectheader or redirecttag) other/page.html
error Error description (if reason is failed) 404 - Not Found

For the Skipped Pages report, the results array is grouped by reason and then ordered by page discovery time.

Duplicate Pages Results

The siteduplicate report lists pages whose content is duplicated on other analyzed pages. Each object in the results array may contain the following subelements:

Element Explanation Example
page Address of page within domain path/page.html
url Full URL of page http://www.example.com/path/page.html
viewurl URL for viewing the duplicate content on this page (available up to 30 days from scan start) https://www.siteliner.com/lmjib545ec/path/page.html?siteliner=duplicate
title Title of page if available News
power Page power (see FAQs) 94
matchwords Total number of words in this page's duplicate content 108
matchpercent Percent of duplicate content in this page 43.5
matchpages Number of other pages with duplicate content matching this page 2

For the Duplicate Pages report, the results array is ordered descending by matchwords.

Internal Broken Links Results

The sitebroken report lists pages containing known broken internal links. Each object in the results array may contain the following subelements:

Element Explanation Example
page Address of page within domain page/page.html
url Full URL of page http://www.example.com/path/page.html
viewurl URL for viewing broken links on this page (available up to 30 days from scan start) https://www.siteliner.com/lmjib545ec/path/page.html?siteliner=broken
title Title of page if available News
power Page power (see FAQs) 94
outlinks Number of pages linked from this page ("nofollow" links included) 3
broken Number of pages with broken links from this page ("nofollow" links excluded) 0

For the Internal Broken Links report, the results array is ordered descending by broken.

Related Domains Results

The siterelateddomain report lists sites with related domains which were linked from analyzed pages. Each object in the results array contains the following subelements:

Element Explanation Example
url Full URL of site with related domain http://www.related.example.com/
inlinks Number of pages found with links to this site ("nofollow" links included) 4

For the Related Domains report, the results array is ordered alphabetically by url.

Page Reports

Request and Response

To retrieve a page report for a completed or stopped scan, send an HTTP GET request to this URL:

https://www.siteliner.com/api

Each API request for a page report costs 1c. Page reports are available for 185 days after the scan was started. Parameters are specified on the URL (using ? and &) as follows:

Parameter Explanation Value Required? Default
user Your username Yes
key Your API key Yes
report Report requested One of: pageduplicate, pagelinkin, pagelinkout, pageexternal Yes
scan Scan ID (from scan field of other API responses) [Scan ID] Yes
page Page (from page or url field of other API responses) [Page or URL, empty for home page] Yes
count Maximum number of results 1 - 100 No 100
start Index of first result to return (see each report's details for ordering) 1 or greater No 1


These APIs return a JSON object containing the following elements:

Element Explanation Example
scan Scan ID lmjib545ec
rooturl Initial URL of scan https://www.example.com/
page Address of page within domain path/page.html
url Full URL of page http://www.example.com/path/page.html
report Provided report parameter pageduplicate
viewurl URL for viewing this report online https://www.siteliner.com/lmjib545ec/path/page.html?siteliner=page-duplicate
title Title of page if available News
resultcount Total results available for this report (ignoring count and start parameters) 31
results Array of result objects, see each report's details below


Example API request to retrieve duplicate report for home page of scan lmjib545ec:

Page Duplicate Results

The pageduplicate report lists other analyzed pages containing content which matches the page provided. Each object in the results array may contain the following subelements:

Element Explanation Example
page Address of matching page within domain other.html
url Full URL of matching page http://www.example.com/other.html
viewurl URL for viewing the matching content (available up to 30 days from scan start) https://www.siteliner.com/lmjib545ec/page.html?siteliner=duplicate&siteliner-item=05c434334aec4037
title Title of matching page if available Other
matchwords Total number of matching words 108
matchpercent Percentage of words matching (out of all words on source page) 43.5

For the Page Duplicate report, the results array is ordered descending by matchwords.

Internal Links In Results

The pagelinkin report lists other analyzed pages which link to the page provided. Each object in the results array may contain the following subelements:

Element Explanation Example
page Address of linking page within domain other.html
url Full URL of linking page http://www.example.com/other.html
title Title of linking page if available Other
power Page power of linking page (see FAQs) 94
links Number of links from linking page to page provided ("nofollow" links included) 94
status Link check if available. One of: ok, nofollow (only if all links are nofollow). ok

For the Internal Links In report, the results array is ordered descending by links.

Internal Links Out Results

The pagelinkout report lists other pages on the site which are linked from the page provided. Each object in the results array may contain the following subelements:

Element Explanation Example
page Address of linked page within domain other.html
url Full URL of linked page http://www.example.com/other.html
title Title of linked page or status details if available Other
links Number of links from page provided to linked page (regular and nofollow), status=nofollow only if they are all nofollow 94
status Link check if available. One of: ok, broken, nofollow, unknown ok

For the Internal Links Out report, the results array is ordered descending by links.

External Links Out Results

The pageexternal report lists external pages which are linked from the page provided. Each object in the results array may contain the following subelements:

Element Explanation Example
url Full URL of external linked page http://www.example.com/page.html
links Number of links from page provided to external linked page 94

For the External Links Out report, the results array is ordered alphabetically by url.

Related Domain Reports

Links In Request and Response

To retrieve a list of analyzed pages which link to a site with a related domain, send an HTTP GET request to this URL:

https://www.siteliner.com/api

The scan must be completed or stopped. Each API request for a report costs 1c. Related Domain reports are available for 185 days after the scan was started. Parameters are specified on the URL (using ? and &) as follows:

Parameter Explanation Value Required? Default
user Your username Yes
key Your API key Yes
report Report requested relatedlinkin Yes
scan Scan ID (from scan field of other API responses) [Scan ID] Yes
url Full URL of site with related domain (must match an url from Related Domains Results) [Site URL] Yes
count Maximum number of results 1 - 100 No 100
start Index of first result (results are ordered descending by the number of links from each page) 1 or greater No 1


This request returns a JSON object containing the following elements:

Element Explanation Example
scan Scan ID lmjib545ec
rooturl Initial URL of scan https://www.example.com/
url Provided URL of site with related domain http://www1.example.com/
report Provided report parameter relatedlinkin
viewurl URL for viewing this report online https://www.siteliner.com/lmjib545ec/http://www.related.example.com/?siteliner=page-linkin
resultcount Total results available for this report (ignoring count and start parameters) 31
results Array of result objects


Each object in the results array may contain the following subelements:

Element Explanation Example
page Address of linking page within scanned domain other.html
url Full URL of linking page http://www.example.com/other.html
title Title of linking page if available Other
power Page power of linking page (see FAQs) 94
links Number of links from linking page to the provided site ("nofollow" links included) 94


Example API request to retrieve Related Domain Links In report of scan lmjib545ec:

Getting Assistance

If you have any questions or problems regarding the API, please contact us.