Create a new dataset using cURL

Follow this guide to prepare a new Dataset for Geckoboard using cURL.

Before you start

cURL is just one of the programming languages you can use to add a Dataset to Geckoboard. We have also have walkthroughs for Node.js, Ruby, and Python.

We also have a dedicated guide to sending SQL data to datasets using either a MacOS, Linux or Windows machine or server.


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

Authenticate your account

Test whether your API key is working by pasting the following command to your terminal.

curl -u "your-api-key:"

Replace your-api-key with your API key. If you missed including the : or are still asked for a password, hit Enter in your terminal.

If authentication is successful {} should be logged to your console.


You can find your API key by following these steps.

Important note

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.

Get help

If you’re having problems with authentication then you can get in contact with our Customer Success team who can assist you.

Make a dataset

You’ll need to give your dataset an id so that you can find it easily in Geckoboard.


Where PUT is the HTTP method that will allow us to create the Dataset and :id is a string to help you identify your dataset from within the application.

Example dataset

In this example we’re creating a dataset with the id sales.by_day.

curl \
  -X PUT \
  -u '222efc82e7933138077b1c2554439e15:' \
  -H 'Content-Type: application/json' \
  -d '{
  "fields": {
    "amount": {
      "type": "number",
      "name": "Amount",
      "optional": false
    "timestamp": {
      "type": "datetime",
      "name": "Date"
  "unique_by": ["timestamp"]


  "id": "sales.by_day",
  "fields": {
    "amount": { "type": "number", "name": "Amount", "optional": false },
    "timestamp": { "type": "datetime", "name": "Date" }
  "unique_by": ["timestamp"]

Before you create your first dataset you’ll need to plan your data’s schema. A schema is a collection of fields which will let us know what form your data takes. Learn more about making datasets.

The Datasets API currently supports the following types:

  • date
  • datetime
  • number
  • percentage
  • string
  • money

Important note

You must use lower case letters for field names.

Read more about types.

Append data to the dataset

You can append records to your dataset by using the POST method. These new records will be added to the existing contents of your datasets.


Should the number of records in your dataset exceed the limit following a POST the oldest records (by insertion time) will be removed. This behaviour can be overridden by using the delete_by option when appending new records.

Example of appending data to the dataset

curl \
  -X POST \
  -u '222efc82e7933138077b1c2554439e15:' \
  -H 'Content-Type: application/json' \
  -d '{
  "data": [
      "timestamp": "2018-01-01T12:00:00Z",
      "amount": 819
      "timestamp": "2018-01-02T12:00:00Z",
      "amount": 409
      "timestamp": "2018-01-03T12:00:00Z",
      "amount": 164



Next steps

Assuming you’ve encountered no errors, then that’s it! You've created a new dataset using cURL.

You can find more detailed information about configuring your dataset in our API Reference.

You can also find instructions on how to delete this dataset.

Suggested next step

Learn how to create a new widget using your new dataset.

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