API Endpoint

The root URL for all Parse.ly API requests is



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

Parameter Description
apikey the API key specified in your Parse.ly JavaScript tracker; Required for all requests.
secret this parameter is required for every request and should contain the secret token obtainable from the API Settings page.
callback to 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.


All Parse.ly 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": [{}, {}, {}, ...]

Inside the data list, the Parse.ly 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 _hits field on both Posts and Metas, indicating the number of pageviews in the selected time period.

The Shares API will return a _shares field on both Posts and Metas, indicating the number of social shares in the selected time period.


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 support@parsely.com.

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 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 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 support@parsely.com. 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::

GET https://api.parsely.com/v2/analytics/posts?apikey=blog.parsely.com


         "title": "How the Facebook News Feed Changes Have Affected Traffic to News Websites",
         "url": "http://blog.parsely.com/post/977/how-the-facebook-news-feed-changes-have-affected-traffic-to-news-websites/",
         "_hits": 274,
         "pub_date": "2013-12-19T00:24:29",
         "author": "Clare O.",
         "section": "Analytics That Matter",
         "tags": ["blog", "analytics"],
         "thumb_url_medium": "http://c0001566.cdn1.cloudfiles.rackspacecloud.com/medium_3d2dbbd7b44f855e2c263551588e1b2db499109f.jpg",
         "image_url": "http://blog.parsely.com/wp-content/uploads/2013/12/authority-report-03-graph-top-domains-small.png",
         "metadata": "{\"num_images\": 3}"
      // ... other top documents ...