Collect a batch of interactions from a Push queue.

An HTTP GET request sent to:


A successful call to this endpoint returns: 200 OK. You also receive a list of JSON objects.


Parameter Description

The id of a Subscription.

Example values: 08b923395b6ce8bfa4d96f57f863a1c3

default = 20971520

The maximum amount of data that DataSift will send in a single batch. Can be any value from 1 byte through 20971520 bytes (20MB). DataSift may deliver slightly more data if the last interaction's boundary falls outside of the given value of the size parameter.


A pointer into the Push queue associated with the current Push subscription.

Take a look at Cursor Management below for more details.


  1. Retrieve one interaction from the Push queue starting from the point identified by the given cursor:

curl -X GET https://api.datasift.com/v1.3/pull?id=d468655cfe5f93741ddcd30bb309a8c7&size=1&cursor=de8f75fd8b0359f457b6a39bd58c43ee 
    -H 'Authorization:username:apikey'

Cursor Management

The cursor parameter is optional. You are free to omit it because DataSift performs full cursor management on your behalf.

Cursors are returned in headers like this:

X-DataSift-Cursor-Current: 011e9ff35c8213dfb7f30002de2f1285
X-DataSift-Cursor-Next: 5814784ca7f1ac8e55aa3b860f58985c
X-DataSift-Bytes-Remaining: 102412345
X-DataSift-Format: json_new_line
Content-Type: application/ldjson

{"interaction":{"content":"Data is awesome"}}
{"interaction":{"content":"Doughnuts are awesome"}}
{"interaction":{"content":"Hiking is awesome"}}

Under normal operation, DataSift uses X-DataSift-Cursor-Next to retrieve the next batch of interactions from your queue.

You can record X-DataSift-Cursor-Next and/or X-DataSift-Cursor-Next and use their values in future calls to the /pull endpoint if you need to.


  1. For any subscription id, you can hit the /pull endpoint no more than twice a second.
  2. All calls to the API must be properly authenticated with a DataSift username and API key.
  3. You must include a Subscription id.
  4. This endpoint is specific to the Pull connector. Read the Pull connector documentation for the full discussion of its behavior.
  5. All calls to the API must be versioned. The current version is v1.3.
  6. Remember that in your call to /push/create you must set the output_type parameter to pull.

Resource information

Rate limit cost: 0

Requires authentication: Yes

Response formats: JSON, JSONP