Skip to content

API: Overview

The root URL for all API requests is


Most of our requests are HTTP GET requests. All requests support the following parameters:

apikeythe Site ID (API key) specified in your JavaScript tracker; Required for all requests.
secretthis parameter is required for every request unless otherwise noted and should contain the secret token obtainable from the API Settings page. Note: The /metadata endpoint uses a distinct write-only secret value. Please reach out to your account manager for details on accessing this write-only secret value.
callbackto support the JSON-P standard, all GET requests can take a callback parameter which will wrap the JSON response in the specified callback function, allowing easy integration into web frontends via JavaScript. also supports Cross-Origin Resource Sharing.


Some endpoints offer the ability to filter by the use of optional parameters based on your metadata. These parameters are case sensitive. If you use the wrong case, you will receive unexpected results such as an empty response.


All API requests are expected to return one or more matching records.

Successful responses are JSON documents using a “data envelope” format, which has this form:

  "data": [{}, {}, {}, ...],
  "meta": {},
  "links": {},
  "success": true

Inside the data list, the API typically returns one of the two following content types:

  • Posts: Content pages with associated metadata, URL, and metrics
  • Metas: Authors, Sections, Tags, etc. with associated metrics

The Analytics API will return a metrics field on both Posts and Metas, containing a mapping of metrics to values.

The Shares API will return a metrics field on both Posts and Metas, containing a mapping of metrics to values.

The meta object contains the list of metrics present in data in the metrics field, as well as how the results were ordered in the sort field.

  "data": [
      "metrics": {
        "avg_engaged": 2.793,
        "engaged_minutes": 162,
        "views": 75,
        "visitors": 58
      "title": "...",
  "success": true,
  "meta": {
    "metrics": [
    "sort": "avg_engaged"
  "links": {...}

The links object contains pagination links. It will always contain a first key, with a link to the first page. A next link will be present if more results are available, otherwise null. A prev link will be available on all pages past the first.

  "data": [...],
  "success": true,
  "meta": {...},
  "links": {
    "first": "",
    "next": "",
    "prev": ""

The API’s numbers will not match exactly the numbers in our dashboard. This is because the dashboard (and the reports/exports subsystem in the dashboard) always makes a strong effort to get “the most exact counts possible”, whereas the API occasionally accepts a small error rate (1-2% typically) in the name of performance/speed. If you are interested in programmatically exporting exact counts of all your data, you should explore our raw data export options by reaching out to

Empty Responses

If you receive an empty response, e.g., {"data": [],..., then it could indicate a mistake in the request. Check the following items of your request:

  • spelling
  • capitalization
  • over-constrained filters

Error Responses

As a matter of practicality, “normal” errors return HTTP Status Code 200 to your client, but encode the error in the JSON document that is returned.

Not Found

If you hit an endpoint below our root endpoint that does not exist, you won’t receive an HTTP 404 status code. You will receive an HTTP 200 status code with the following document contents:

  "message": "Not Found",
  "code": 404,
  "success": false


If you attempt to access sensitive data with an invalid Site ID (apikey) or secret, you won’t receive an HTTP 403 status code. Instead, you will receive an HTTP 200 status code with the following document contents:

  "message": "Forbidden",
  "code": 403,
  "success": false

Invalid parameters

If you make a request with parameters that seems invalid (ie passing page anything other than a number), the API will now return what the error is so you can corect it. The HTTP response code from the API will still be 200. Example:

  "code": 422,
    "page": ["Not a valid integer."]
  "message": "Bad parameters: page",
  "success": false

Other Errors

Other error conditions will take a similar form.

If you receive an HTTP status code other than 200 (e.g. 500 – Internal Server Error), something is wrong with our API, and you should notify us at @ParselySupport on Twitter or If you receive a “normal” error condition with "code": 500, something may be misconfigured on your account.


An example request to the analytics API might look like this::



     "title": "How the Facebook News Feed Changes Have Affected Traffic to News Websites",
     "url": "",
     "_hits": 274,
     "pub_date": "2013-12-19T00:24:29",
     "author": "Clare O.",
     "section": "Analytics That Matter",
     "tags": ["blog", "analytics"],
     "thumb_url_medium": "",
     "image_url": "",
     "full_content_word_count": 435,
     "metadata": "{"num_images": 3}"
     "metrics": {
      "views": 274
   // ... other top documents ...

Triggering a new article crawl

The workflow for triggering a new crawl of an article is slightly different from the calls described above. Refer to our documentation on that here.

Last updated: October 24, 2023