preview/get

Retrieve a Historics preview.

An HTTPS GET request sent to:

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

A successful call to this endpoint returns: 200 OK plus a JSON object.

Parameters

Parameter Description
id
required

The hash of the definition to preview. You receive the hash when you make a successful call to /preview/create. The preview id must exist. The preview id must belong to the requesting user. Previews expire after 14 days.

Example values: e25d533cf287ec44fe66e8362f61961f

Examples

  1. The following is an example of a call to /v1.3/preview/get. You must supply your credentials and the Historics preview id:

    curl -X GET https://api.datasift.com/v1.3/preview/get?id=e25d533cf287ec44fe66e8362f61961f 
        -H 'Authorization:username:apikey'

Output

Calls to /preview/get return two types of successful responses. Which one you receive depends on the status of the Historics Preview query. There are two indicators you can use to monitor what is going on: status and progress.

Status: Running (HTTP Code: 202 Accepted)

When status is set to running, responses to call to /preview/get return a short form JSON object. The value of the progess key indicates how much of the query has been completed. It is an integer whose value can be anything from 0 to 100.

{
    "id": "8d38093ce3a78fbbba6f",
    "progress": 5,
    "status": "running",
    "feeds": "twitter",
    "sample": 1,
    "end": 1359936000,
    "created_at": 1362409489,
    "start": 1359849600,
    "user": "12919",
    "parameters": "interaction.content,wordCount,10",
    "hash": "93558e17de15072fa126370c37c5bd8f"
}

Status: Succeeded (HTTP Code: 200 OK)

When a Historics Preview job is finished and the results are ready for delivery, a call to /preview/get will return a long-form JSON response. The value of the progress key will be set to 100 and the value of the status key will be set succeeded. The results of the analyses performed by your Historics Preview will be given in the value of the data key. It is a list of dictionaries, each being a result of a separate analysis for a specific target.

{
    "id": "c59ce40e865f1704b233",
    "progress": 100,
    "status": "succeeded",
    "feeds": "twitter",
    "sample": 1,
    "end": 1359936000,
    "created_at": 1362500299,
    "start": 1359849600,
    "user": "12919",
    "parameters": "interaction.author.link,targetVol,hour;twitter.user.lang,freqDist,10;twitter.user.followers_count,numStats,hour;interaction.content,wordCount,10",
    "hash": "93558e17de15072fa126370c37c5bd8f",
    "data": [
        {
            "target": "interaction.author.link",
            "analysis": "targetVol",
            "output": {
                "2013/02/03 21:00:00": 483,
                "2013/02/03 20:00:00": 455,
                "2013/02/03 16:00:00": 371,
                "2013/02/03 07:00:00": 212,
                "2013/02/03 23:00:00": 3727,
                "2013/02/03 14:00:00": 272,
                "2013/02/03 19:00:00": 453,
                "2013/02/03 13:00:00": 218,
                "2013/02/03 15:00:00": 328,
                "2013/02/03 08:00:00": 181,
                "2013/02/03 11:00:00": 149,
                "2013/02/03 10:00:00": 158,
                "2013/02/03 12:00:00": 183,
                "2013/02/03 09:00:00": 162,
                "2013/02/03 22:00:00": 543,
                "2013/02/03 18:00:00": 437,
                "2013/02/03 06:00:00": 261,
                "2013/02/03 17:00:00": 396
            },
            "interval": "hour"
        },
        {
            "target": "twitter.user.lang",
            "analysis": "freqDist",
            "output": {
                "fr": 30,
                "pt": 37,
                "it": 7,
                "nl": 10,
                "de": 12,
                "ru": 8,
                "id": 26,
                "en": 5450,
                "es": 544,
                "ja": 8
            },
            "threshold": 10
        },
        {
            "target": "twitter.user.followers_count",
            "analysis": "numStats",
            "output": {
                "2013/02/03 21:00:00": {
                    "min": 1,
                    "max": 50239,
                    "count": 287,
                    "sum": 267468
                },
                "2013/02/03 20:00:00": {
                    "min": 1,
                    "max": 115771,
                    "count": 264,
                    "sum": 462205
                },
                "2013/02/03 16:00:00": {
                    "min": 1,
                    "max": 24212,
                    "count": 258,
                    "sum": 217525
                },
                "2013/02/03 07:00:00": {
                    "min": 1,
                    "max": 7295,
                    "count": 158,
                    "sum": 76463
                },
                "2013/02/03 23:00:00": {
                    "min": 1,
                    "max": 3017366,
                    "count": 2458,
                    "sum": 6667940
                },
                "2013/02/03 14:00:00": {
                    "min": 1,
                    "max": 84525,
                    "count": 192,
                    "sum": 238159
                },
                "2013/02/03 19:00:00": {
                    "min": 1,
                    "max": 4299615,
                    "count": 290,
                    "sum": 4621461
                },
                "2013/02/03 13:00:00": {
                    "min": 1,
                    "max": 1002323,
                    "count": 168,
                    "sum": 1410864
                },
                "2013/02/03 15:00:00": {
                    "min": 1,
                    "max": 4299885,
                    "count": 250,
                    "sum": 8931897
                },
                "2013/02/03 08:00:00": {
                    "min": 1,
                    "max": 667865,
                    "count": 128,
                    "sum": 929846
                },
                "2013/02/03 11:00:00": {
                    "min": 1,
                    "max": 15981,
                    "count": 118,
                    "sum": 90075
                },
                "2013/02/03 10:00:00": {
                    "min": 1,
                    "max": 146451,
                    "count": 119,
                    "sum": 227252
                },
                "2013/02/03 12:00:00": {
                    "min": 1,
                    "max": 102826,
                    "count": 131,
                    "sum": 296061
                },
                "2013/02/03 09:00:00": {
                    "min": 1,
                    "max": 146454,
                    "count": 125,
                    "sum": 365938
                },
                "2013/02/03 22:00:00": {
                    "min": 1,
                    "max": 52317,
                    "count": 350,
                    "sum": 329469
                },
                "2013/02/03 18:00:00": {
                    "min": 1,
                    "max": 4299653,
                    "count": 292,
                    "sum": 5310219
                },
                "2013/02/03 06:00:00": {
                    "min": 1,
                    "max": 34646,
                    "count": 196,
                    "sum": 196230
                },
                "2013/02/03 17:00:00": {
                    "min": 1,
                    "max": 198732,
                    "count": 270,
                    "sum": 437504
                }
            },
            "interval": "hour"
        },
        {
            "target": "interaction.content",
            "analysis": "wordCount",
            "output": {
                "blackberry": 561,
                "super": 433,
                "disney": 1009,
                "audi": 352,
                "commercial": 1670,
                "doritos": 763,
                "godaddy": 439,
                "taylor": 603,
                "bowl": 421,
                "swift": 592
            },
            "threshold": 10
        }
    ]
}

Errors

When things go wrong, the Historics Preview API responds with the following errors:

Preview Not Found (HTTP Code: 404 Not Found)

Returned when you supply a non-existent Historics Preview id. If you forget the id, simply create a new Historics Preview with a call to /preview/create.

{
   "error": "Preview not found"
}

Preview Failed (HTTP Code: 400 Bad Request)

Returned when you forget to supply a Historics Preview id. If you forget the id, simply create a new Historics Preview with a call to /preview/create.

{
   "error": "Preview failed"
}

Notes

  1. All calls to the API must be properly authenticated with a DataSift username and API key.
  2. All calls to the API must be versioned. The current version is v1.3.

Resource information

Rate limit cost: 5

Requires authentication: Yes

Response formats: JSON, JSONP