Push to Dash

Pushing Data to Dash

If you have a Pro or Business account, you can update custom widgets by pushing data. This lets you write software that pushes new data to a dashboard, and then see everything update a split-second later.

We've decided to limit push widgets to paid accounts because, quite simply, it costs us more money. If your dashboard has pull custom widgets and you have it loaded for 30 minutes a day, we only have to pull data during those 30 minutes. But, if you're pushing data to us, you're probably sending data all of the time, even when someone isn't viewing the dashboard.

Getting the Push URL

Every Custom Push Widget has its own URL, and you can get it by going to the widget's configuration screen:

Specifying Content-Type

Most widgets support data in more than one format, so you'll need to tell us what kind of data you're sending. You do this by specifying the Content-Type in the request header. Although no widget in Dash supports all of these, the supported content type options are:
  • application/json
  • text/plain
  • text/csv
  • text/html
For example, if you're sending us JSON data, the Content-Type HTTP header would look like:
Content-Type: application/json

Push Examples

Push widgets are updated by sending an HTTP PUT or POST to the widget's Push URL. Each custom widget type has its own data format, so be sure to check the individual widget pages for more information.

For example, let's update a basic value widget to show the phrase, "Hi there."
curl -X PUT -d "Hi there." -H "content-type: text/plain" https://push.thedash.com/custom/v1/QkU0DDmI/2b2af1e0-abe6-11e4-a232-2166454db5e2
The server then replies with:
{success: true}
and the widget now looks like this:

Here's a little more complicated example. We're sending JSON to a speedometer widget. Notice how the content type is now application/json.
curl -X PUT -H "content-type: application/json" -d '{"value": 10500, "formatted": "10.5k"}' https://push.thedash.com/custom/v1/QkU0DDmI/39502eb0-4acf-11e5-948c-371e336113ab
After the update the speedometer widget looks like this:

You can even push CSV data to widgets that support CSV. In this example, I've saved the following text as chart.csv.
We then run the following command from the same directory as we've saved chart.csv:
curl -X PUT -H "content-type: text/plain; charset=UTF-8" --data-binary @chart.csv -k https://push.thedash.com/custom/v1/QkU0DDmI/98904480-4ad1-11e5-948c-371e336113ab
The chart widget will then look like this:

Finally, if you want to clear your widget's data, you can send an HTTP DELETE request:
curl -X DELETE https://push.thedash.com/custom/v1/QkU0DDmI/2b2af1e0-abe6-11e4-a232-2166454db5e2

Streaming via WebSockets

If you want to get really fancy, you can even set up a WebSocket connection and stream updates. You use the widget's same push URL, but feel free to replace the https:// with wss:// (both work just fine).

In this example we'll be using WebSocket Cat. First we install it with:
npm install -g wscat
and then we connect to the widget.
wscat -c https://push.thedash.com/custom/v1/QkU0DDmI/2b2af1e0-abe6-11e4-a232-2166454db5e2
Our terminal window now looks like this:

We'll type in our widget update and hit return. This is our terminal now:

and this is our widget:

Rate Limits

Requests modifying widgets are limited to 500 requests per hour. The requests are associated with the dashboard id and widget identifier. In other words, each push URL has its own rate limits.

You can check the HTTP headers on the response to see the current rate limit status:
HTTP/1.1 200 OK
X-Request-Id: d91a2d5b-cd8e-42af-aeb9-fc80c6e2ad62
X-RateLimit-Limit: 500
X-RateLimit-Remaining: 238
X-RateLimit-Reset: 1421336560
Content-Type: text/html; charset=utf-8
Content-Length: 2
Date: Thu, 15 Jan 2015 14:23:28 GMT
Connection: keep-alive

Here are the relevant headers:
  • X-RateLimit-Limit: Number of requests permitted in an hour.
  • X-RateLimit-Remaining: Number of requests remaining in the current rate limit window.
  • X-RateLimit-Reset: UTC epoch seconds which the current rate limit window resets.

If you go over the rate limit, you'll receive an error response with a status code of 429.
HTTP/1.1 429 Too Many Requests
Server: nginx/1.6.0
Date: Thu, 15 Jan 2015 14:48:40 GMT
Content-Type: text/html; charset=utf-8
Content-Length: 19
Connection: keep-alive
X-Request-Id: ff5eae9a-8b76-4e41-8e8c-9e795d23e1e2
X-RateLimit-Limit: 500
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1421336560
Retry-After: 3238.713
{"message":"Rate limit exceeded"}


Your requests may generate errors. Error responses will be a JSON object with a message field describing the problem. Here's a list of errors and their codes:

400 - Bad Request

Something is invalid with your request. It's most likely caused by your data not being formatted correctly.

403 - Forbidden

You can't use the push api unless you have a Pro or Business account.
{"message":"Forbidden - Only pro and business accounts can push."}

404 - Not Found

This resource doesn't exist.
HTTP/1.1 404 Not Found
X-Request-Id: e8ed1c61-2d6c-401e-8e10-fcfa78efa393
Content-Type: application/json; charset=utf-8
Content-Length: 23
ETag: W/"17-358bf97c"
Date: Wed, 14 Jan 2015 23:43:05 GMT
Connection: keep-alive
{"message":"Not Found"}

413 - Request Too Large

We'll send this error if you're sending us too much data. You should rarely run into this error, but if you do, email us at hello@thedash.com and we'll see if we can accommodate your needs.

415 - Invalid content type

See the "Specifying Content-Type" section above to see what content types we support.

429 - Rate limited

You've been rate limited. See the "Rate Limits" section above for more details.

500 - Blue Smoke

You may run into miscellaneous server errors. When we're having problems on our end, we'll send a server error code 500. We really don't want this to happen, so if it does, please report it to hello@thedash.com.
HTTP/1.1 500 Internal Server Error
X-Request-Id: f00e24c7-8ded-473c-9033-32ee116c8028
X-RateLimit-Limit: 240
X-RateLimit-Remaining: 211
Content-Type: application/json; charset=utf-8
Content-Length: 91
Date: Wed, 14 Jan 2015 23:42:03 GMT
Connection: keep-alive
{"message":"Uh, oh. We're running into some technical issues. Try again in a few minutes!"

Feedback and Knowledge Base