Data Buckets

A Data Bucket is a container for storing data that is visualized dashboard widgets.

Key Features

• Three Bucket Types - Timestamp Key, String Key, or Integer Key with 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

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

TSV keys: You can use unix timestamps in milliseconds or ISO 8601 timestamp strings. The examples on this page use unix millisecond timestamps.

Data structure:

{
  "k": 1760954400000,
  "d": [
    {"sk": 1, "v": 25.5},
    {"sk": 2, "v": 23.1}
  ]
}

• k - Timestamp key (unix timestamp in milliseconds)
• 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)

Integer Key + Series Values (IV)

Records are indexed by integer key. Each record contains an integer key and multiple series values.

Use cases: Ordered categorical ranges, histogram buckets, ranked data, numeric lookup tables

Data structure:

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

• k - Integer 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": 1760954400000,
      "data": [
        {"series_key": 1, "value": 25.5},
        {"series_key": 2, "value": 23.1}
      ]
    }
  ]'

Examples below use unix millisecond timestamps. ISO 8601 timestamp strings are also accepted for TSV writes.

Example 2: Write Single Record (Timestamp Key as ISO 8601 String)

Using an ISO 8601 timestamp string for the same TSV write:

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": 1760954400000,
      "data": [
        {"series_key": 1, "value": 25.5},
        {"series_key": 2, "value": 23.1}
      ]
    },
    {
      "key": 1760954460000,
      "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}
      ]
    }
  ]'

Write Multiple Records (Integer Keys)

Creating multiple records with integer 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": 1,
      "data": [
        {"series_key": 1, "value": 45.2},
        {"series_key": 2, "value": 52.1}
      ]
    },
    {
      "key": 2,
      "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 unix millisecond timestamps in chronological order and 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

Integer Key + Series Values (IV) Buckets

When you insert records into IV buckets:

• Integer keys: Each record key must be an integer
• Upsert behavior: Writing to an existing integer key replaces all series values for that key
• Range queries supported: You can query integer key ranges with from and to
• Best practice: Use integer keys for ordered numeric buckets or ranked ranges

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

Example:

Existing record:

{
  "k": 1737280800000,
  "d": [
    {"sk": 1, "v": 100},
    {"sk": 2, "v": 200}
  ]
}

Writing new data:

[
  {
    "k": 1737280800000,
    "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": 1737280800000,
    "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: For TSV buckets, use either a unix timestamp in milliseconds or an ISO 8601 timestamp string. KV buckets use strings, and IV buckets use integers.
• 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": 1760954460000,
      "ca": "2025-10-20T10:01:05Z",
      "1": 25.7,
      "2": 23.3
    },
    {
      "k": 1760954400000,
      "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)
• from / to: Supported for TSV timestamp ranges and IV integer-key ranges. For TSV, you can use unix milliseconds or ISO 8601 timestamp strings.

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": 1760954400000,
      "ca": "2025-10-20T10:00:05Z",
      "1": 25.5,
      "2": 23.1
    }
  ]
}

API Delete Data

Delete Individual Record in KV or IV Bucket

Deletes an individual record from a KV (String Key) or IV (Integer Key) bucket:

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

⚠️ Important:

• This works for KV buckets (string keys) and IV buckets (integer keys).
• 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": 1737280800000,
      "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