All API responses are formatted as either XML or JSON. XML responses are the default. For JSON responses, add format=json to the request URL query string.
The default daily limit for API calls is 1,000 calls per day. The daily count resets every night at midnight UTC. If you would like to exceed the daily limit, just talk to us.
- Under the Options menu, click Account Management.
- In the Account Management pop-up, select Account Settings.
- Click on the New API Key button.
- In the pop-up, click Yes to generate a new API key and deactivate the old one.
You can make an API request right within your browser address bar, as long as you know your API key and the STAT subdomain that your account is on. (For example, “app2.getstat.com” or “public3.getstat.com.” You can see this in the address bar when you are logged into the app.)
These details are used to create an API request URL:
- XML request:
- JSON request:
- Typical example:
To find the appropriate request URL string, see API requests and responses.
Using the optional specialty services
- In the Site Tools, click Settings.
- Choose which optional API service you would like to activate and select the format if appropriate.
- Click Save.
- In the main menu bar, select Options > Account Management.
- In the pop-up, select Billing in the left menu to see your overall charges for optional services.
- Select Optional Services in the left menu to see a detailed breakdown of charges by site.
March 28, 2018
STAT reporting and API have all Yahoo data removed.
New error response code added: 429 = Too many requests.
Sep 13, 2017
Changed the download URL for your API archives. Your API data is stored directly on S3, which results in a different download URL. This change helps facilitate larger downloads and creates greater download stability.
Bulk HTML SERP API
Bulk SERP API
Bulk Adwords API
Bulk Export Jobs
Site Ranking Distributions
Tag Ranking Distributions
Old URL example:
New URL example:
June 28, 2017
Individual results may have multiple universal result types, e.g. amp AND carousel AND news.
All results that appear in a carousel will have the same rank. For example, if a carousel appears in the third position on a SERP, all carousel entries will be ranked #3.
January 18, 2017
When passing an incorrect year format (i.e. not YYYY), the Billing API calls (Billing:Bill, Billing:User breakdown, and Billing:Site breakdown) will return “response=500. Wrong year format. The year parameter must be in the format YYYY.”
The Billing:User API call will no longer return user data in subsequent billing periods after it has been deleted, but will still show data in billing periods where the user had accrued a charge.
January 13, 2017
Corrected an issue with backslashes that caused JSON formatted output for Bulk SERPs to be invalid. Keywords ending with \ will now be escaped properly, appearing as \\ .
December 13, 2016
Updated the Bulk export jobs:Ranks API call (/bulk/ranks) back-end processing workflow to queue jobs for same-day requests with unavailable data, instead of returning an error message.
December 7, 2016
Added new API calls for share of voice scores matching CSV export content, and for top competitors at the site and tag levels.
Added new API calls for billing. Returns data for Billing Overview, User Breakdown, and Site Breakdown. Billing APIs are only available to admin users, and do not count towards the daily calls count limit.
October 26, 2016
Removed requirement for API location parameter (&location=) when doing a Keywords:Create call. (Previously, if location wasn’t included, the call would fail and some clients wouldn’t be notified with an error message.)
Corrected an issue with the Keywords:List call that produced inconsistencies in the ranking dates being returned. Each rank will now uniformly return data from the previous day of the call.
July 6, 2016
Added protocol to Bulk Serps and updated list of possible result types for all SERP requests.
Added ability to select which search engine data the Bulk Ranks export returns.
Added ability to choose between highest ranks (previous implementation) and all ranks in the Bulk Ranks export.
April 22, 2016
Added guard to Rankings:List, SERPs:Show, Sites:Ranking Distributions, Tags:Ranking Distributions, and the Bulk export jobs:Ranks / Site Ranking Distributions / Tag Ranking Distributions to only allow these requests after data has been fully collected for a day.
Added error message documentation to API calls that may return specific error messages.
January 20, 2016
Added <Synced> to response from Sites:All and Sites:List.
December 2, 2015
Added functionality to list an admin user’s subaccounts via Subaccounts:List.
Added functionality to allow users to delete multiple keywords with a comma-separated string of keyword id’s via the /keywords/delete API method.
August 17, 2015
Removed references to tag colors, backlinks, and indexed pages from our API.
July 20, 2015
Released JSON version of our optional API services. To trigger JSON format, add &format=json to the end of any API request.
April 30, 2015
Released JSON version of our API. To trigger JSON format, add &format=json to the end of any API request.
April 29, 2015
Added <FolderId> and <FolderName> to response from Sites:All and Sites:List.
April 22, 2015
Added functionality to escape comma with a backslash when adding a keyword that contains a comma.
February 18, 2015
Modified output of Bulk XML SERP API. Each SERP result is now wrapped in a <Result> node.
January 23, 2015
Added pagination to BulkJob:list. Modified the sorting order to descending order by Bulk Job ID.
December 17, 2014
Added <JobType>html-serps</JobType> to BulkJob:list
Removed <StreamURL> from response if <JobType>html-serps</JobType>
December 11, 2014
Added <Type> to response from Tags:list
November 19, 2014:
If <JobType>serp</JobType> or <JobType>adwords</JobType>:
Replaced <Site> with <SiteTitle> and <SiteUrl> in response from BulkJob:list
Added <Project> and <Folder> to response from BulkJob:list
January 9, 2014:
Modified <Url> and <StreamUrl> for BulkJob:list and BulkJob:status
October 25, 2013:
Removed <PageRank> from API entirely.
October 10, 2013:
Removed <DisplayRank> from Serps:show and Rankings:list
October 9, 2013:
Added currently_tracked_only & crawled_keywords_only parameters to /bulk/ranks API call
August 9, 2013:
Added Sites:ranking_distributions API call
Added Tags:ranking_distributions API call
Added Bulk:site_ranking_distributions API call
Added Bulk:tag_ranking_distributions API call
Adjusted formatting of document
June 4, 2013:
Corrected an error in the documentation. ‘batch_size’ parameter replaced with ‘results’ parameter in Sites:all, Keywords:list, Tags:list
May 16, 2013:
Added <LocalSearchTrendsByMonth> to response from Keywords:list and Bulk:ranks
May 13, 2013:
Added batch_size parameter to Sites:all,Keywords:list,Tags:list
Mar 7, 2013:
Added Tags:list API call
Feb 28, 2013:
Added <Title> to Response parameters for Sites:all, Sites:list
Changed match_subdomain and track_backlinks params to drop_www_prefix and drop_directories in Sites:create,Sites:update
Added <Title>,<DropWWWPrefix>,<DropDirectories> from Response parameters for Sites:create,Sites:update
Removed <MatchSubdomain>,<TrackBacklinks> from Response parameters for Sites:create,Sites:update
Jan 11, 2013:
Added <PageRank> to Sites:all, Sites:list
Added <StreamUrl> to Bulkjobs:list, Bulkjobs:status
Nov 20, 2012:
Added <CPC> to response from Keywords:list
Added <CPC> to output file created by Bulkjobs:ranks
Added <KeywordLocation> to output file created by Bulkjobs:ranks
Added <KeywordLocation> to response from Keywords:list, Keywords:create
Added location= request parameter to Keywords:create
Removed type= request parameter from Keywords:create
Removed <KeywordType> from response to Keywords:list, Keywords:create
Removed <KeywordCategories> from response to Keywords:list
Sept 29, 2011:
Removed <TrackBacklinks> <MatchSubdomain> from all Site calls.
Removed <PageTitle> <Abstrasct> from Rankings:list and Serps:show
Added <BaseRank> and <DisplayRank> responses to Rankings:list and Serps:show
Added <ResultType> to Serps:show