Data Buckets

A Data Bucket is a container for storing time-series or key-value data that powers your dashboard widgets.

Key Features

• Two Bucket Types - Timestamp Key + Series Values or String Key + Series Values
• Multi-Series Support - Multiple data series per record
• Real-Time Updates - WebSocket connections for instant widget updates
• High Performance - Optimized for high-throughput data ingestion
• Minified Format - Bandwidth-efficient data transmission
• Flexible Access - API keys or session-based authentication

Bucket Types

Timestamp Key + Series Values (TSV)

Records are indexed by timestamp. Each record contains a timestamp key and multiple series values.

Use cases: Metrics over time, sensor readings, monitoring data

Data structure:

{
  "k": "2025-10-20T10:00:00Z",
  "d": [
    {"sk": 1, "v": 25.5},
    {"sk": 2, "v": 23.1}
  ]
}

• k - Timestamp key (ISO 8601 format)
• d - Array of series values
• sk - Series key (integer identifier)
• v - Numeric value (float)

String Key + Series Values (KV)

Records are indexed by string. Each record contains a string key and multiple series values.

Use cases: Configuration data, state storage, categorical metrics

Data structure:

{
  "k": "2025",
  "d": [
    {"sk": 1, "v": 45.2},
    {"sk": 2, "v": 52.1}
  ]
}

• k - String key
• d - Array of series values
• sk - Series key (integer identifier)
• v - Numeric value (float)

Bucket Scope

Data buckets are scoped to a specific dashboard. When you create a bucket, it belongs to one dashboard and can only be accessed by widgets on that dashboard.

Data Retention

Configure how many records are retained in your buckets:

• Default retention - Records are kept indefinitely
• Custom retention - Set maximum number of records to retain (e.g., keep latest 1,000 records)
• Automatic purge - When the record limit is exceeded, oldest records are automatically removed

Retention settings are configured per dashboard and apply to all buckets within that dashboard.

API Write Data

Example 1: Write Single Record (Timestamp Key)

Creating one record with a timestamp key:

curl -X POST https://data.dashgrid.com/api/buckets/{BUCKET_ID} \
  -H "Content-Type: application/json" \
  -H "X-API-Key: {YOUR_API_KEY}" \
  -d '[
    {
      "key": "2025-10-20T10:00:00Z",
      "data": [
        {"series_key": 1, "value": 25.5},
        {"series_key": 2, "value": 23.1}
      ]
    }
  ]'

Write Multiple Records (Timestamp Keys)

Creating multiple records with timestamp keys in one request:

curl -X POST https://data.dashgrid.com/api/buckets/{BUCKET_ID} \
  -H "Content-Type: application/json" \
  -H "X-API-Key: {YOUR_API_KEY}" \
  -d '[
    {
      "key": "2025-10-20T10:00:00Z",
      "data": [
        {"series_key": 1, "value": 25.5},
        {"series_key": 2, "value": 23.1}
      ]
    },
    {
      "key": "2025-10-20T10:01:00Z",
      "data": [
        {"series_key": 1, "value": 25.7},
        {"series_key": 2, "value": 23.3}
      ]
    }
  ]'

Write Single Record (String Key)

Creating one record with a string key:

curl -X POST https://data.dashgrid.com/api/buckets/{BUCKET_ID} \
  -H "Content-Type: application/json" \
  -H "X-API-Key: {YOUR_API_KEY}" \
  -d '[
    {
      "key": "2024",
      "data": [
        {"series_key": 1, "value": 45.2},
        {"series_key": 2, "value": 52.1}
      ]
    }
  ]'

Write Multiple Records (String Keys)

Creating multiple records in one request:

curl -X POST https://data.dashgrid.com/api/buckets/{BUCKET_ID} \
  -H "Content-Type: application/json" \
  -H "X-API-Key: {YOUR_API_KEY}" \
  -d '[
    {
      "key": "2024",
      "data": [
        {"series_key": 1, "value": 45.2},
        {"series_key": 2, "value": 52.1}
      ]
    },
    {
      "key": "2025",
      "data": [
        {"series_key": 1, "value": 78.5}
      ]
    }
  ]'

How Data Records Insertion Works

Timestamp Key + Series Values (TSV) Buckets

When you insert records into TSV buckets:

• Automatic sorting: Records are merged into chart data in continuous descending order (newest first)
• Upsert behavior: Writing to an existing timestamp replaces all series values for that timestamp
• Historical data: Adding records with timestamps in the past is computationally heavy at scale
• Best practice: Send data in chronological order, avoid backdating records when possible

String Key + Series Values (KV) Buckets

When you insert records into KV buckets:

• Preserved order: Records are appended in the exact order you submit them
• No automatic sorting: Dashgrid intentionally preserves your submission order
• Upsert behavior: Writing to an existing key replaces all series values for that key
• Best practice: Submit records in the order you want them displayed

Important: For both bucket types, Dashgrid does NOT merge or append series values - it performs a complete replacement of the record.

Example:

Existing record:

{
  "k": "2025-01-19T10:00:00Z",
  "d": [
    {"sk": 1, "v": 100},
    {"sk": 2, "v": 200}
  ]
}

Writing new data:

[
  {
    "k": "2025-01-19T10:00:00Z",
    "d": [
      {"sk": 1, "v": 150}
    ]
  }
]

Result: The record is completely replaced. Series 2 is gone, and series 1 now has value 150.

Empty Data Arrays:

You can send an empty data array to clear all series for a specific key:

[
  {
    "k": "2025-01-19T10:00:00Z",
    "d": []
  }
]

This will create or update the record with no data points, effectively clearing all series data for that key while keeping the record itself.

API Reference

Endpoint: POST https://data.dashgrid.com/api/buckets/{BUCKET_ID}

Authentication: X-API-Key: {YOUR_API_KEY} header

Field Specifications:

• key: Timestamp (ISO 8601 format like 2025-10-20T10:00:00Z) for TSV buckets, or any string for KV buckets
• data: Array of series values (0-10 items per record)
• series_key: Integer between 1 and 10, must be unique within the record
• value: Number (integer or float), cannot be null

Minified Format: You can use shortened field names (k, d, sk, v) instead of full names for bandwidth efficiency. Both formats are accepted.

API Read Data

Get Multiple Records

curl https://data.dashgrid.com/api/buckets/{bid}/records?limit=10&offset=0 \
  -H "X-API-Key: {YOUR_API_KEY}"

Response (flattened format with k key, ca created_at, and the series keys as string numbers):

{
  "records": [
    {
      "k": "2025-10-20T10:01:00Z",
      "ca": "2025-10-20T10:01:05Z",
      "1": 25.7,
      "2": 23.3
    },
    {
      "k": "2025-10-20T10:00:00Z",
      "ca": "2025-10-20T10:00:05Z",
      "1": 25.5,
      "2": 23.1
    }
  ]
}

Query parameters:

• limit (integer, optional): Number of records to return (default: 100, max: 1000)
• offset (integer, optional): Number of records to skip (default: 0)

Get One Record

Response (flattened format with k key, ca created_at, and the series keys as string numbers):

curl https://data.dashgrid.com/api/buckets/{bid}/records/{record_key} \
  -H "X-API-Key: {YOUR_API_KEY}"

Response:

{
  "records": [
    {
      "k": "2025-10-20T10:00:00Z",
      "ca": "2025-10-20T10:00:05Z",
      "1": 25.5,
      "2": 23.1
    }
  ]
}

API Delete Data

Delete Individual Record in KV Bucket (KV, String Key)

Deletes an individual record from (KV, String Key) bucket:

curl -X DELETE https://data.dashgrid.com/api/buckets/{BUCKET_ID}/records/{KEY} \
  -H "X-API-Key: {YOUR_API_KEY}"

⚠️ Important:

• This only works for KV buckets (KV, String Key).
• For buckets with timestamp keys (TSV, timestamp), individual deletion is not supported because it creates gaps in the time-series and prevents proper data retention window management.

Clear Individual Record Values in TSV Bucket (Timestamp Keys)

Writes an empty data array to clear values while preserving the timestamp:

curl -X POST https://data.dashgrid.com/api/buckets/{BUCKET_ID} \
  -H "Content-Type: application/json" \
  -H "X-API-Key: {YOUR_API_KEY}" \
  -d '[
    {
      "key": "2025-01-19T10:00:00Z",
      "data": []
    }
  ]'

API Purge Data

Deletes all records in a bucket. This can be triggered via API when you need to clear a bucket and start fresh.

curl -X DELETE https://data.dashgrid.com/api/buckets/{BUCKET_ID}/purge \
  -H "X-API-Key: {YOUR_API_KEY}"

⚠️ Important:

• all records in the bucket will be permanently deleted
• data counter will be reset for this bucket
• deleting a bucket in the Dashgrid app, also deteletes all data records

API Error Responses

401 Unauthorized

{"error": "API key required"}

Missing or invalid X-API-Key header.

403 Forbidden

{"error": "permission denied"}

API key doesn't have access to this bucket's dashboard.

404 Not Found

{"error": "bucket not found"}

Bucket ID doesn't exist.

400 Bad Request

{"error": "validation error: d.sk must be integer between 1 and 10"}

Invalid request data. Common validation errors:

• Key format invalid for bucket type
• Data array has more than 10 items
• Series key not between 1-10
• Duplicate series keys in same record
• Null values in data points