Title: API: Overview
Author: staff
Published: August 1, 2022
Last modified: July 20, 2026

---

 1. [The Parse.ly API](https://docs.parse.ly/api/)
 2. API: Overview

#  API: Overview

The root URL for all Parse.ly API requests is

    ```lang-php
    https://api.parsely.com/v2/
    ```

## Request

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

| Parameter | Description | 
| apikey | the Site ID (API key) specified in your Parse.ly JavaScript tracker; Required for all requests. | 
| secret | this parameter is required for every request unless otherwise noted and should contain the secret token obtainable from the [API Settings](http://dash.parsely.com/to/settings/api) page. **Note**: The [`/metadata` endpoint](https://docs.parse.ly/api-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. | 
| 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. Parse.ly also supports Cross-Origin Resource Sharing. |

**Note**

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.

## Response

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:

    ```lang-php
    {
      "data": [{}, {}, {}, ...],
      "meta": {},
      "links": {},
      "success": true
    }
    ```

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 `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.

    ```lang-php
    {
      "data": [
        {
          "metrics": {
            "avg_engaged": 2.793,
            "engaged_minutes": 162,
            "views": 75,
            "visitors": 58
          },
          "title": "...",
        }],
      "success": true,
      "meta": {
        "metrics": [
          "engaged_minutes",
          "avg_engaged",
          "visitors",
          "views"
        ],
        "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.

    ```lang-php
    {
      "data": [...],
      "success": true,
      "meta": {...},
      "links": {
        "first": "http://api.parsely.com/v2/...&page=1",
        "next": "http://api.parsely.com/v2/...&page=3",
        "prev": "http://api.parsely.com/v2/...&page=1"
      }
    }
    ```

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 [Parse.ly Support](https://support.parse.ly/hc/en-us).

## 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:

    ```lang-php
    {
      "message": "Not Found",
      "code": 404,
      "success": false
    }
    ```

## Forbidden

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:

    ```lang-php
    {
      "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:

    ```lang-php
    {
      "code": 422,
      "errors":
      {
        "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 [Parse.ly Support](https://support.parse.ly/hc/en-us).
If you receive a “normal” error condition with `"code": 500`, something may be misconfigured
on your account.

## Example

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

    ```lang-php
    GET https://api.parsely.com/v2/analytics/posts?apikey=blog.parsely.com
    ```

Response:

    ```lang-php
    {
      "data":[
       {
         "title": "How the Facebook News Feed Changes Have Affected Traffic to News Websites",
         "url": "https://blog.parse.ly/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": "https://blog.parse.ly/wp-content/uploads/2013/12/authority-report-03-graph-top-domains-small.png",
         "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](https://docs.parse.ly/whats-a-recrawl/).

Last updated: July 20, 2026