canonical: https://jentic.com/apis/geckoboard.com/geckoboard

# Geckoboard Datasets API

The Geckoboard Datasets API lets teams push their own structured data into Geckoboard, where it is then displayed on real-time KPI dashboards on TVs, monitors, and team boards. The API exposes six operations covering dataset definition (find or create with a typed schema), full append, batch append, replace, and delete, alongside a root verification endpoint. Auth is HTTP Basic with the Geckoboard API key as the username - no separate OAuth flow. It is purpose-built for teams that already have data in a warehouse, app, or script and need it visible on a wall display in seconds.

## For AI agents

Push custom datasets to Geckoboard for real-time dashboard visualisation, and append, replace, or delete records by dataset id.

## Scope

Does not handle SQL queries, raw event ingestion, or alerting - use for pushing typed datasets to Geckoboard dashboards only.

## Capabilities

- Verify API credentials by calling GET / before pushing any data
- Find or create a dataset with a typed schema using PUT `/datasets/{dataset_id}`
- Append records to an existing dataset via POST `/datasets/{dataset_id}/data` without overwriting history
- Replace the entire contents of a dataset with PUT `/datasets/{dataset_id}/data` for full snapshot updates
- Delete a dataset with DELETE `/datasets/{dataset_id}` when a metric is retired

## Use cases

### Wall-Display KPIs From An Internal App

Stream live counters - orders per hour, active users, support tickets - from your own backend to a Geckoboard wall display. The agent calls PUT `/datasets/{dataset_id}` once to define the schema, then POST `/datasets/{dataset_id}/data` on every update to append rows. Replaces fragile screenshot-based status TVs.

Example prompt: PUT `/datasets/orders_hourly` with the typed schema, then POST `/datasets/orders_hourly/data` with the latest hour's record on a 5-minute cron

### Snapshot Reporting For Sales Pipelines

Replace the Geckoboard dataset entirely each evening with the current state of the sales pipeline so the morning standup board shows live deal counts by stage. The agent calls PUT `/datasets/{dataset_id}/data` with the full payload, eliminating drift between CRM and dashboard.

Example prompt: PUT `/datasets/sales_pipeline/data` with the full array of {stage, count, value} rows queried from the CRM at midnight

### Batch Append From An ETL Job

When an ETL run finishes, push only the rows that changed instead of replacing the whole dataset. The agent batches the new records and calls POST `/datasets/{dataset_id}/data` with up to the supported batch size, leaving historical rows in place. Reduces network volume and keeps Geckoboard's history charts intact.

Example prompt: POST `/datasets/{dataset_id}/data` with the batch of records produced by the ETL run; rerun on next ETL trigger

### Agent-Driven Dashboarding Through Jentic

AI agents discover Geckoboard via Jentic, load the dataset push operation, and stand up a live KPI board for a team in minutes - without writing a custom client. Jentic isolates the basic-auth API key in its vault. Useful for ops bots that surface anomalies on a shared display.

Example prompt: Use Jentic search query 'push data to a Geckoboard dataset' to load the geckoboard_push_data tool and execute with dataset_id and the records array

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | `/` | Verify the API key with a no-op root call |
| PUT | `/datasets/{dataset_id}` | Find or create a dataset with a typed schema |
| POST | `/datasets/{dataset_id}/data` | Append records to a dataset |
| PUT | `/datasets/{dataset_id}/data` | Replace all records in a dataset |
| DELETE | `/datasets/{dataset_id}` | Delete a dataset |

## Key resources

- **Datasets** — Define schemas and manage typed datasets visible on Geckoboard dashboards
- **Data** — Append or replace dataset records to drive live KPI widgets

## Why Jentic

- **Setup:** Wiring the Geckoboard Datasets API by hand means setting up HTTP basic auth with your API key as the username against api.geckoboard.com and coordinating dataset create, push, and replace calls yourself. Through Jentic you install once, import the Geckoboard Datasets API from the API Directory, store the key once, and your agent calls it.
- **Permission scoping:** Geckoboard puts the dataset id in the URL path (`/datasets/{dataset_id}/data`), so a rule can pin your agent to one dataset: it can create and push data to that dataset and nothing else. You choose the operations it may call, so deleting the dataset is not included unless you add it.
- **Credential handling:** Your Geckoboard API key is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'push data to a Geckoboard dataset' or 'create a dataset', and Jentic returns the matching Geckoboard Datasets operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **Tableau API** — Tableau provides full BI dashboards over connected data sources; Geckoboard targets simple custom KPI displays driven by pushed datasets.
- **Slack API** — Notify a channel when a Geckoboard KPI crosses a threshold by pairing the dataset push with a Slack message.
- **OpenAI API** — Use OpenAI to summarise a Geckoboard dataset and generate a daily plain-language commentary on the KPIs.

## FAQ

### What authentication does the Geckoboard Datasets API use?

HTTP Basic with the Geckoboard API key as the username and an empty password. Through Jentic the key is stored encrypted in the vault and the basic-auth header is injected per request.

### Can I append records to a Geckoboard dataset without replacing it?

Yes. POST `/datasets/{dataset_id}/data` appends the supplied records and preserves existing history, which is the right call for incremental ETL updates.

### How do I create a new dataset with the Geckoboard API?

Call PUT `/datasets/{dataset_id}` with a typed schema. The endpoint is find-or-create - if a dataset with that id already exists with a matching schema, the call is a no-op; otherwise it is created.

### What are the rate limits for the Geckoboard Datasets API?

Geckoboard does not declare rate-limit headers in the spec. Treat HTTP 429 as a back-off signal and follow Geckoboard's published guidance on push frequency in their documentation.

### How do I delete a Geckoboard dataset?

Call DELETE `/datasets/{dataset_id}.` The dataset and all its records are removed from your Geckoboard account, so widgets bound to that id will stop rendering.

### How do I push data through Jentic?

Install with pip install jentic, search 'push data to a Geckoboard dataset', load the geckoboard_push_data operation schema, and execute with the dataset id and the records array.

### Can I limit what my agent is allowed to do with the Geckoboard Datasets API?

Yes. Because Jentic One is self-hosted and runs under your own rules, you decide which Geckoboard operations the agent may call and which API key it uses. Since the dataset id sits in the URL path (`/datasets/{dataset_id}/data`), you can pin the agent to a single dataset so it only creates and appends or replaces records there. You can also withhold DELETE `/datasets/{dataset_id}`, so the agent pushes data but cannot remove a dataset unless you grant it.