Getting started with the Datasets API

Geckoboard’s Datasets API lets you compile data from in-house systems, third-party tools, and databases on a simple dashboard. Instantly accessible via sharing links, mobile, TV screens, it allows developers and team members to get the exact numbers they need – without the headache.

You can access the Datasets API on the command line using cURL or through a client built in whichever language you prefer. We provide walkthroughs for our Node.js, Ruby, and Python clients.

If you think you may need some help integrating with the Datasets API, you can reach out to our Customer Success team.

What is a dataset?

Datasets are best thought of as tables. Your dataset’s schema defines the fields – or 'columns' – of this table to let Geckoboard know what structure your data takes. You can include up to 10 different fields in a dataset, so one dataset can easily power a whole dashboard. Fields have, at minimum, a name and a type.

Here's an example of an dataset:

Unit cost
money (USD)
Profit margin
Shipping date
















The relationship between the way you're able to visualize the dataset and the schema it uses is key. A well thought-through schema will make it much easier to configure your widgets when it comes to adding them to your Geckoboard dashboard.

Read the schema formatting and visualization types section to see which ones are available and how to shape your schema for a particular one.

Install a client library

We provide official libraries for different programming languages.

If you're on a Unix based OS (Mac, Linux), you likely have it installed on your machine. Regardless of the OS you're using, you can check with the curl -V command on your terminal to see if you have it installed.

If you need to install cURL, please visit their download page for instructions.


Windows users can access the Command Prompt by searching for Command within Cortana.Searching for command within Cortana in Windows

We’ll be using the Geckoboard Node.js library to make a simple Node.js app. Node.js version 4+ is required.

First, create a new directory for your Node.js app.

Next, in your terminal, cd to your app’s directory and run:

npm install geckoboard

To begin, add this line to your application’s Gemfile:

gem 'geckoboard-ruby'

And then execute:

$ bundle

Alternatively, install it yourself as:

$ gem install geckoboard-ruby

Require the gem and create an instance of the client:

require 'geckoboard'
client = Geckoboard.client(api_key)

It's likely that you have python installed on your machine. Here are instructions on how to check based on the OS you're currently using. You'll also find instructions on how to install python in case you don't yet have it.

Install the python client from PIP

pip install

Important note

These instructions are for code stored in the same directory as the client. The standard import method for packages should be used if is being stored elsewhere.

Authenticate your Geckoboard account

Authenticate your account when using the Datasets API by including your personal API key in the request.

What's an API key?

An API key is an authorization code used to identify you as the requester. You can find your Geckoboard API key by following these steps.

Your Geckoboard API key is just as powerful as your login credentials, so keep it safe. Do not share it in publicly accessible areas such GitHub, client-side code, and so forth.

You can test if your API key is working by peplacing your-api-key with your API key. Make sure you keep the colon (:) in the request.

curl -u "your-api-key:"

You should get a 200 response containing {}


If you missed including the : or are still asked for a password, simply hit the Enter key on your terminal.

Verify that your API key is valid with the #ping method:;
Attribute Type Required?
  callback Function Yes

Verify that your API key is valid with the ping method:


Geckoboard.client('good-api-key').ping # => true
Geckoboard.client('bad-api-key').ping # => raises Geckoboard::UnauthorizedError

Verify that your API key is valid with the ping method:


client('good-api-key').ping() # => true
client('bad-api-key').ping() # => raises Exception

Plan your schema

When you’re adding a dataset widget to your dashboard, we’ll look at your schema and present the visualization options that make sense for the types of data you’re sending us. For example, to plot a line chart the dataset must contain the date or datetime types.

Visualizations are powered by individual datasets, which means you can't combine data from two or more datasets to build a visualization

Geckoboard can handle data aggregation and grouping, so there’s no need to pre-aggregate your data. And when an update is received via the API, all the widgets powered by that dataset are then updated automatically.

The Datasets API currently supports the following types:

Next step

You're ready to begin creating your first dataset using our walkthroughs for cURL, Node.js, Ruby, and Python.

Was this article helpful?

Awesome! 👍 Thanks so much for your feedback!

Sorry about that! Start a conversation now.

We're ready to help, 24 hours a day, 5 days a week

Get support
  • Fernanda Customer Success Avatar


  • Hariharan Customer Success Avatar


  • Fernanda Customer Success Avatar


  • Luis Customer Success Avatar


  • Richard Customer Success Avatar


  • Fernanda Customer Success Avatar


  • Heather Customer Success Avatar