API Docs

Version:  1.0

Bulk API

Upgrading from the old endpoint

Users on paid plans have access to a bulk querying endpoint, where you can POST a large batch of URLs all at once, and poll for the result once its ready. Responses will be in JSON. This endpoint will not be available in JSONP.

URLs are transmitted one per line in the POST body, with a trailing line-break after the final URL.

For example, you would query:

POST https://YOUR_APP_PLAN.sharedcount.com/bulk?apikey=YOUR_APP_KEY

Request Body:
http://www.google.com/
http://www.amazon.com/

Please see pricing page for detailed quota information and information on paid plans with extra API quota.

Batch size


The maximum number of URLs you can query in a batch depends on your plan:

  • Plus: 500
  • Business: 1,000
  • Dedicated: 10,000

Successfully completed API queries done via batching will count against your daily API quota. Requests exceeding your API quota will be rejected. Under the covers, the bulk endpoint acts as a layer on top of the existing API; one which handles the queueing and processing of a large number of queries for the purposes of reducing transit overhead.

When you make your POST request, you'll receive a response giving you a bulk_id, and also the number of URLs that were accepted and queued for querying. Invalid URLs will be silently ignored.

The bulk_id can be used to fetch the completed response:

GET YOUR_APP_PLAN.sharedcount.com/bulk?apikey=YOUR_APP_KEY&bulk_id=:bulk_id

When you make this request, you'll get back an object indicating the number of URLs completed thus far. If all of the queued URLs are complete, the full data will be returned. When this complete state is reached and your full data is returned, further requests for that bulk_id may no longer return data.

If you want to receive your data incrementally while it's being churned, you can add a &force=1 parameter to the URL, and each request will contain the completed URL data up until that point:

GET YOUR_APP_PLAN.sharedcount.com/bulk?apikey=YOUR_APP_KEY&bulk_id=:bulk_id&force=1

This can be useful if for some reason one or two URLs remain outstanding for an extended period of time.