Skip to main content

Get Bucket

Retrieve details of a specific bucket.

Endpoint​

GET /api/buckets/:id

Authentication​

Key TypeAllowed
Admin (dakkio_a_)✅ Yes
Write (dakkio_w_)❌ No
Read (dakkio_r_)❌ No

Required: Admin key (dakkio_a_). Only Admin keys can retrieve bucket details.

Request​

Headers​

HeaderTypeRequiredDescription
X-API-Keystring✅ YesYour Admin API key

Path Parameters​

ParameterTypeRequiredDescription
idstring✅ YesThe bucket ID (24-character hex string)

Example Request​

curl -X GET "https://api.dakkio.io/api/buckets/507f1f77bcf86cd799439011" \
-H "X-API-Key: dakkio_a_your_admin_key..."

Response​

Success Response (200 OK)​

{
"bucket": {
"_id": "507f1f77bcf86cd799439011",
"name": "Home Sensors",
"description": "Temperature and humidity sensors for my home",
"organizationId": "507f1f77bcf86cd799439000",
"createdAt": "2024-01-10T08:00:00Z",
"updatedAt": "2024-01-15T10:30:00Z",
"stats": {
"dataSourceCount": 3,
"dataPointCount": 15420,
"apiKeyCount": 2
}
}
}

Error Responses​

400 Bad Request - Invalid ID​

{
"error": "Validation Error",
"message": "Invalid bucket ID format"
}

401 Unauthorized​

{
"error": "Unauthorized",
"message": "Invalid or missing API key"
}

403 Forbidden​

{
"error": "Forbidden",
"message": "Only Admin keys can access bucket details"
}

404 Not Found​

{
"error": "Not Found",
"message": "Bucket not found"
}

Code Examples​

JavaScript/Node.js​

const axios = require('axios');

async function getBucket(bucketId) {
const response = await axios.get(
`https://api.dakkio.io/api/buckets/${bucketId}`,
{
headers: {
'X-API-Key': process.env.DAKKIO_ADMIN_KEY
}
}
);

return response.data.bucket;
}

// Get bucket details
const bucket = await getBucket('507f1f77bcf86cd799439011');
console.log(`Bucket: ${bucket.name}`);
console.log(`Data points: ${bucket.stats.dataPointCount}`);

Python​

import requests
import os

def get_bucket(bucket_id):
response = requests.get(
f'https://api.dakkio.io/api/buckets/{bucket_id}',
headers={
'X-API-Key': os.environ['DAKKIO_ADMIN_KEY']
}
)

if response.status_code == 200:
return response.json()['bucket']
else:
print('Error:', response.json())
return None

# Get bucket details
bucket = get_bucket('507f1f77bcf86cd799439011')
if bucket:
print(f"Bucket: {bucket['name']}")
print(f"Data points: {bucket['stats']['dataPointCount']}")

Response Fields​

FieldTypeDescription
_idstringUnique bucket identifier
namestringBucket name
descriptionstringBucket description
organizationIdstringOrganization that owns the bucket
createdAtstringCreation timestamp (ISO 8601)
updatedAtstringLast update timestamp (ISO 8601)
stats.dataSourceCountnumberNumber of data sources in bucket
stats.dataPointCountnumberTotal data points stored
stats.apiKeyCountnumberNumber of API keys for this bucket