Create a preview of a Historics query.

note icon

Check out What is Historics Preview? and read our Historics API step-by-step page to learn more.

An HTTPS POST request sent to:

A successful call to this endpoint returns: 202 Accepted plus a JSON object.


Parameter Description

UTC timestamp to start the report from; this will be rounded to the previous hour. The start must be on or after midnight, January 1st 2010 and prior to (now - 2 hours). Please make sure that you understand the concept of time zones, UTC, and convert date and time to UTC before you submit it to DataSift. You can use an online converter.

Example values: 1325548800


UTC timestamp at which to end the report. The end must be greater than or equal to start, and prior to now - 1 hour. If not specified, defaults to start + 1 day. This will be rounded to the next hour. You can analyze up to a month of data in one Historics Preview job.

Example values: 1325549800


The hash of the filter to preview.

Example values: 2459b03a13577579bca76471778a5c3d


Comma-separated list of data sources to include. In the future, you will be able to choose any source listed as a valid value that you would use in the interaction.type target. Currently, you can use any of the sources shown here.

Example values: twitter, facebook, bitly, tumblr


A list of at least one but no more than 20 Historics Preview parameters each formatted as a comma-separated string:


Historic Preview parameters are separated with semicolons (;), for example,targetVol,hour;interaction.type,freqDist,10

Each parameter defines the target and the statistical analysis to be performed on that target along with an optional argument that customizes its results. You have a choice of four types of statistical analyses you can perform on a selected target:

freqDist - target frequency distribution. This analysis takes a threshold argument that controls the number of values returned in the output (max 100). For example, if you want to know the frequency distribution of the top 10 languages used in the matching interactions, you would specify:


numStats - results of a numeric statistical analysis of the given target. The values of the given target will be analyzed in hourly intervals, and for each interval you will receive minimum, maximum, count, and sum values.

targetVol - returns how many times the specified target appears in the results, in hourly intervals.

wordCount - returns a list of up to 100 most often used words found in the specified target inside the 1 percent stream that the new Historics Preview will be based on. For example, if you are doing an analysis of conversations happening on Twitter and you want top ten words found in the matching Tweets, set this parameter to:


Not all targets can be analyzed using all types of statistical analysis. See our preview types matrix for help. For examples of the output, see /preview/get.

Example values:,targetVol,hour;interaction.type,freqDist,10


  1. Here is an example of a call to /v1.3/preview/create:

curl -X POST 
    -d 'start=1359849600' 
    -d 'hash=e25d533cf287ec44fe66e8362f61961f' 
    -d ',targetVol,hour;twitter.user.lang,freqDist,10;twitter.user.followers_count,numStats,hour;interaction.content,wordCount,10' 
    -d 'sources=twitter,facebook' 
    -H 'Authorization: datasift-user:your-datasift-api-key'


Successful calls to /preview/create return HTTP Code: 202 Accepted.

Status: Running (HTTP Code: 202 Accepted)

A success response will contain the GUID (hash) of the new preview. The initial status of each new Historics Preview job is set to queued. If you want to monitor the progress of your query, you need to call /preview/get.

    "id": "3ddb72ca02389dbf3b46",
    "created_at": 1364303060


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

No stream found for the given hash (HTTP Code: 404 Not Found)

Returned when you supply a non-existent stream hash id. If you forget the id of the stream you want to use for the Historics Preview, call /usage.

    "error": "No stream found for the given hash"

Start must be at least two hours ago (HTTP Code: 400 Bad Request)

The timestamp given as the value of the start parameter was set to a value smaller than current UTC - 7200 seconds. Adjust the value of the start timestamp and try again.

    "error": "Start must be at least two hours ago"

End must be at least one hour ago (HTTP Code: 400 Bad Request)

The timestamp given as the value of the end parameter was set to a value smaller than current UTC - 3600 seconds. Adjust the value of the end timestamp and try again.

    "error": "End must be at least one hour ago"

Target invalid (HTTP Code: 400 Bad Request)

You made a typo in the target name. Correct it and try again.

    "error": "Target invalid"

analysisName is an invalid analysis for (HTTP Code: 400 Bad Request)

You are trying to perform a statistical analysis that does made sense for the chosen target, for example, cannot be analyzed using targetVol.

    "error": "wordCount is an invalid analysis for"


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

Requires authentication: Yes

Response formats: JSON, JSONP