push/get

Show details of the Subscriptions belonging to this user.

An HTTP GET request sent to:

https://api.datasift.com/v1.3/push/get

A successful call to this endpoint returns: 200 OK.

Parameters

Parameter Description
id
optional

The id of a Subscription.

Example values: 08b923395b6ce8bfa4d96f57f863a1c3

hash
optional

The hash of a live stream.

Example values: 5465fa0683583e96b21a1faddbca4ea8

historics_id
optional

The historics_id of a Historics query.

Example values: 4ef7c852a96d6352764f

page
optional
default = 1

The page number.

Example values: 7

per_page
optional
default = 20

The number of items to return per page.

Example values: 16

order_by
optional
default = created_at

The field that DataSift will use to order the results, created_at or updated_at.

Example values: created_at

order_dir
optional
default = desc

The direction of the ordering.
Ascending (asc) or descending (desc).

Example values: asc

include_finished
optional

Set it to 1 to include finished Subscriptions (for Historics queries) in the response.

Example values: 1

Examples

  1. Retrieve a list of your subscriptions and list them, in descending alphabetical order, 50 to a page, including Subscriptions that have finished running:

    curl -X GET https://api.datasift.com/v1.3/push/get?per_page=50&order_dir=desc&include_finished=1 
        -H 'Authorization:username:apikey'

    Here's an example of the output:

    {
          "count": 2,
          "subscriptions": [
              {
                  "id": "d668655cfe5f93741ddcd30bb309a8c7",
                  "output_type": "dynamodb",
                  "name": "mypushsubscription1",
                  "created_at": 1365430066,
                  "hash": "42d388f8b1db997faaf7dab487f11290",
                  "hash_type": "stream",
                  "output_params": {
                      "table": "datasift-dynamodb",
                      "region": "dynamodb.eu-west-1.amazonaws.com"
                  },
                  "status": "active",
                  "last_request": null,
                  "last_success": null,
                  "remaining_bytes": null,
                  "lost_data": false,
                  "start": 0,
                  "end": 0,
                  "interaction_count":12345
              },
              {
                  "id": "d468655cfe5f93741ddcd30bb309a8c7",
                  "output_type": "dynamodb",
                  "name": "mypushsubscription2",
                  "created_at": 1365430066,
                  "hash": "42d388f8b1db997faaf7dab487f11290",
                  "hash_type": "stream",
                  "output_params": {
                      "table": "datasift-dynamodb",
                      "region": "dynamodb.eu-west-1.amazonaws.com"
                  },
                  "status": "active",
                  "last_request": null,
                  "last_success": null,
                  "remaining_bytes": null,
                  "lost_data": false,
                  "start": 0,
                  "end": 0,
                  "interaction_count":54321
              }
          ]
      }

    Property: Description:
    count The number of subscriptions returned by this call to /push/get.
    subscriptions A JSON list of subscriptions. Each subscription is a JSON object whose elements are listed below.
    id A unique id for each Push subscription. Each subscription has a unique id, even when they are based on the same stream and the data is delivered to the same destination.
    output_type The name of the connector you're using with this Push request.
    name A user-defined name of the subscription.
    created_at A Unix timestamp that represents the date and time when the subscription was created.
    hash A stream id or Historics query id.
    hash_type Can be either "stream" (when the hash element represents a stream) or "historics" (when the hash element represents a Historics query).
    output_params output_parameters used in the call to /push/create.
    status The subscription status.
    last_request The time of the most recent Push delivery request sent to the associate data destination. A Unix timestamp.
    last_success The time of the most recent successful delivery. A Unix timestamp.
    remaining_bytes The number of bytes queued for delivery.
    lost_data Set to true if data was removed from the Push delivery queue because it could not be delivered.
    start Subscription start time/date. A Unix timestamp.
    end Subscription end time. A Unix timestamp.
    interaction_count The number of interactions including deletes that we've delivered to the destination. It is NULL if you don't supply a subscription id.
  2. Retrieve details of one subscription:

    curl -X GET 'https://api.datasift.com/v1.3/push/get' 
        -d 'id=d468655cfe5f93741ddcd30bb309a8c7' 
        -d 'per_page=50' 
        -d 'order_dir=desc' 
        -d 'include_finished=1' 
        -H 'Authorization: datasift-user:your-datasift-api-key'

    Here's what the output looks like:

    {
          "id": "d468655cfe5f93741ddcd30bb309a8c7",
          "output_type": "dynamodb",
          "name": "mypushsubscription1",
          "created_at": 1365430066,
          "hash": "42d388f8b1db997faaf7dab487f11290",
          "hash_type": "stream",
          "output_params": {
              "table": "datasift-dynamodb",
              "region": "dynamodb.eu-west-1.amazonaws.com"
          },
          "status": "active",
          "last_request": null,
          "last_success": null,
          "remaining_bytes": null,
          "lost_data": false,
          "start": 0,
          "end": 0,
          "interaction_count": 1234
      }

Paging

In cases where you have a large number of Subscriptions, you can use the page and per_page parameters. The per_page parameter is optional. If you omit it and you do no specify a Historics id, DataSift retrieves details of the first 20 Historics queries it finds.

If you set per_page at 50, for example, and leave the page parameter blank or set page to 1, DataSift returns the first 50 objects it finds.

If you set per_page to 50 and set page to 3, for example, DataSift assumes that each 'page' of results contains 50 objects; it discards the first 2 pages that it finds (in other words, it discards 100 objects) and gives you the next 50 objects. If each object were numbered, this would mean you receive objects 101 to 150.

For more details, take a look at the Push API overview.

Notes

  1. All calls to the API must be properly authenticated with a DataSift username and API key.
  2. If you include a Subscription id, DataSift retrieves details for that Subscription only.
  3. If you supply a hash, DataSift retrieves all the Subscriptions for that hash.
  4. If you supply a historics_id, DataSift retrieves all the Subscriptions for that historics_id.
  5. If you omit all three of these parameters, DataSift returns a list of all your subscriptions.
  6. The /push/get endpoint retrieves details of your Historics queries and returns the number specified by the per_page parameter.
  7. Push subscriptions that have finished successfully or failed are displayed by the push/get endpoint for up to one week; after that, they expire and disappear from the results.
  8. All calls to the API must be versioned. The current version is v1.3.

Revision history

v1.1

In the output, we added an interaction_count field. It returns the number of interactions including deletes that we've delivered to the destination. It is NULL if you don't supply a subscription id.

Prior to v1.1, playback_id was a synonym for the historics_id parameter. The playback_id parameter is no longer supported. You must use historics_id.

Resource information

Rate limit cost: 1

Requires authentication: Yes

Response formats: JSON, JSONP