API Documentation (Scale+ Only)

Access your Dashtray data programmatically with our REST API.

Overview

The Dashtray API allows Scale and Agency plan users to:

Fetch metrics and time series data
Retrieve dashboard configurations
Push custom metrics via webhooks
Integrate with external tools and workflows

Availability: Scale and Agency plans only

Base URL

https://api.dashtray.com/v1

Authentication

API Keys

Navigate to Settings → API Keys
Click Create API Key
Give your key a descriptive name
Copy the key (starts with pp_)
Save it securely (you won’t see it again)

Using API Keys

Include your API key in the Authorization header:

Authorization: Bearer pp_your_api_key_here

Example Request

curl -H "Authorization: Bearer pp_your_api_key_here" \
  https://api.dashtray.com/v1/metrics

Rate Limiting

Limit: 1,000 requests per hour per project
Headers: Rate limit info included in response headers

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1640000000

Rate Limit Exceeded

When limit is exceeded, you’ll receive:

{
  "error": "Rate limit exceeded",
  "message": "You have exceeded the rate limit of 1000 requests per hour",
  "retryAfter": 3600
}

Status Code: 429 Too Many Requests

Endpoints

GET /metrics

Fetch metrics with optional filtering. Parameters:

projectId (required): Your project ID
metricIds (optional): Comma-separated metric IDs
startDate (optional): ISO 8601 date (e.g., 2024-01-01T00:00:00Z)
endDate (optional): ISO 8601 date
limit (optional): Results per page (default: 100, max: 1000)
offset (optional): Pagination offset (default: 0)

Example Request:

curl -H "Authorization: Bearer pp_your_api_key" \
  "https://api.dashtray.com/v1/metrics?projectId=proj_123&metricIds=stripe_mrr,github_commits&startDate=2024-01-01T00:00:00Z&limit=100"

Example Response:

{
  "data": [
    {
      "id": "metric_abc123",
      "projectId": "proj_123",
      "connectionId": "conn_456",
      "service": "stripe",
      "metricId": "stripe_mrr",
      "metricName": "Monthly Recurring Revenue",
      "value": 15000,
      "unit": "USD",
      "timestamp": 1704067200000,
      "metadata": {
        "currency": "USD",
        "subscriptionCount": 150
      },
      "createdAt": 1704067200000
    },
    {
      "id": "metric_def456",
      "projectId": "proj_123",
      "connectionId": "conn_789",
      "service": "github",
      "metricId": "github_commits",
      "metricName": "Commits",
      "value": 42,
      "unit": "count",
      "timestamp": 1704067200000,
      "metadata": {
        "repositories": ["repo1", "repo2"]
      },
      "createdAt": 1704067200000
    }
  ],
  "pagination": {
    "total": 250,
    "limit": 100,
    "offset": 0,
    "hasMore": true
  }
}

Status Codes:

200 OK: Success
400 Bad Request: Invalid parameters
401 Unauthorized: Invalid or missing API key
403 Forbidden: Insufficient permissions
429 Too Many Requests: Rate limit exceeded

GET /metrics/:metricId/timeseries

Fetch time series data for a specific metric. Parameters:

projectId (required): Your project ID
startDate (required): ISO 8601 date
endDate (required): ISO 8601 date
interval (optional): hour, day, week, month (default: day)

Example Request:

curl -H "Authorization: Bearer pp_your_api_key" \
  "https://api.dashtray.com/v1/metrics/stripe_mrr/timeseries?projectId=proj_123&startDate=2024-01-01T00:00:00Z&endDate=2024-01-31T23:59:59Z&interval=day"

Example Response:

{
  "data": [
    {
      "timestamp": 1704067200000,
      "value": 14500
    },
    {
      "timestamp": 1704153600000,
      "value": 14750
    },
    {
      "timestamp": 1704240000000,
      "value": 15000
    }
  ],
  "metric": {
    "id": "stripe_mrr",
    "name": "Monthly Recurring Revenue",
    "unit": "USD",
    "service": "stripe"
  },
  "interval": "day",
  "startDate": "2024-01-01T00:00:00Z",
  "endDate": "2024-01-31T23:59:59Z"
}

Status Codes:

200 OK: Success
400 Bad Request: Invalid parameters
401 Unauthorized: Invalid or missing API key
404 Not Found: Metric not found
429 Too Many Requests: Rate limit exceeded

GET /dashboards

Fetch all dashboards for a project. Parameters:

projectId (required): Your project ID

Example Request:

curl -H "Authorization: Bearer pp_your_api_key" \
  "https://api.dashtray.com/v1/dashboards?projectId=proj_123"

Example Response:

{
  "data": [
    {
      "id": "dash_abc123",
      "projectId": "proj_123",
      "name": "Executive Summary",
      "slug": "executive-summary",
      "type": "custom",
      "isDefault": false,
      "createdBy": "user_456",
      "createdAt": 1704067200000,
      "updatedAt": 1704067200000
    },
    {
      "id": "dash_def456",
      "projectId": "proj_123",
      "name": "Payments",
      "slug": "payments",
      "type": "category",
      "category": "payment",
      "isDefault": true,
      "createdBy": "user_456",
      "createdAt": 1704067200000,
      "updatedAt": 1704067200000
    }
  ]
}

Status Codes:

200 OK: Success
401 Unauthorized: Invalid or missing API key
429 Too Many Requests: Rate limit exceeded

GET /dashboards/:dashboardId

Fetch a specific dashboard with its widgets. Example Request:

curl -H "Authorization: Bearer pp_your_api_key" \
  "https://api.dashtray.com/v1/dashboards/dash_abc123"

Example Response:

{
  "data": {
    "id": "dash_abc123",
    "projectId": "proj_123",
    "name": "Executive Summary",
    "slug": "executive-summary",
    "type": "custom",
    "isDefault": false,
    "createdBy": "user_456",
    "createdAt": 1704067200000,
    "updatedAt": 1704067200000,
    "widgets": [
      {
        "id": "widget_123",
        "dashboardId": "dash_abc123",
        "type": "metric",
        "title": "MRR",
        "position": {
          "x": 0,
          "y": 0,
          "w": 3,
          "h": 2
        },
        "visible": true,
        "config": {
          "metricId": "stripe_mrr",
          "connectionId": "conn_456",
          "timeRange": "30d"
        },
        "createdAt": 1704067200000,
        "updatedAt": 1704067200000
      },
      {
        "id": "widget_456",
        "dashboardId": "dash_abc123",
        "type": "chart",
        "title": "Revenue Trend",
        "position": {
          "x": 3,
          "y": 0,
          "w": 6,
          "h": 3
        },
        "visible": true,
        "config": {
          "metricId": "stripe_revenue",
          "connectionId": "conn_456",
          "chartType": "line",
          "timeRange": "90d",
          "aggregation": "sum"
        },
        "createdAt": 1704067200000,
        "updatedAt": 1704067200000
      }
    ]
  }
}

Status Codes:

200 OK: Success
401 Unauthorized: Invalid or missing API key
404 Not Found: Dashboard not found
429 Too Many Requests: Rate limit exceeded

POST /metrics/custom

Push custom metrics to Dashtray via webhook. Request Body:

{
  "projectId": "proj_123",
  "metricId": "custom_metric_name",
  "value": 1234.56,
  "timestamp": 1704067200000,
  "unit": "USD",
  "metadata": {
    "source": "custom_system",
    "category": "revenue"
  }
}

Example Request:

curl -X POST \
  -H "Authorization: Bearer pp_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "projectId": "proj_123",
    "metricId": "custom_sales",
    "value": 5000,
    "timestamp": 1704067200000,
    "unit": "USD"
  }' \
  https://api.dashtray.com/v1/metrics/custom

Example Response:

{
  "success": true,
  "metricId": "metric_xyz789",
  "message": "Custom metric created successfully"
}

Field Descriptions:

projectId (required): Your project ID
metricId (required): Unique identifier for your custom metric
value (required): Numeric value
timestamp (optional): Unix timestamp in milliseconds (defaults to now)
unit (optional): Unit of measurement (e.g., “USD”, “count”)
metadata (optional): Additional key-value pairs

Status Codes:

201 Created: Success
400 Bad Request: Invalid request body
401 Unauthorized: Invalid or missing API key
429 Too Many Requests: Rate limit exceeded

Error Responses

All errors follow this format:

{
  "error": "Error type",
  "message": "Human-readable error message",
  "details": {
    "field": "Additional error details"
  }
}

Common Error Codes

400 Bad Request:

{
  "error": "Bad Request",
  "message": "Invalid parameter: startDate must be a valid ISO 8601 date"
}

401 Unauthorized:

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

403 Forbidden:

{
  "error": "Forbidden",
  "message": "API access requires Scale or Agency plan"
}

404 Not Found:

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

429 Too Many Requests:

{
  "error": "Rate Limit Exceeded",
  "message": "You have exceeded the rate limit of 1000 requests per hour",
  "retryAfter": 3600
}

500 Internal Server Error:

{
  "error": "Internal Server Error",
  "message": "An unexpected error occurred. Please try again later."
}

Code Examples

JavaScript/Node.js

const axios = require('axios');

const API_KEY = 'pp_your_api_key';
const BASE_URL = 'https://api.dashtray.com/v1';

async function getMetrics(projectId) {
  try {
    const response = await axios.get(`${BASE_URL}/metrics`, {
      headers: {
        'Authorization': `Bearer ${API_KEY}`
      },
      params: {
        projectId,
        limit: 100
      }
    });

    console.log('Metrics:', response.data);
    return response.data;
  } catch (error) {
    console.error('Error:', error.response?.data || error.message);
  }
}

getMetrics('proj_123');

Python

import requests

API_KEY = 'pp_your_api_key'
BASE_URL = 'https://api.dashtray.com/v1'

def get_metrics(project_id):
    headers = {
        'Authorization': f'Bearer {API_KEY}'
    }
    params = {
        'projectId': project_id,
        'limit': 100
    }

    response = requests.get(f'{BASE_URL}/metrics', headers=headers, params=params)

    if response.status_code == 200:
        print('Metrics:', response.json())
        return response.json()
    else:
        print('Error:', response.json())

get_metrics('proj_123')

cURL

# Get metrics
curl -H "Authorization: Bearer pp_your_api_key" \
  "https://api.dashtray.com/v1/metrics?projectId=proj_123&limit=100"

# Get time series
curl -H "Authorization: Bearer pp_your_api_key" \
  "https://api.dashtray.com/v1/metrics/stripe_mrr/timeseries?projectId=proj_123&startDate=2024-01-01T00:00:00Z&endDate=2024-01-31T23:59:59Z"

# Push custom metric
curl -X POST \
  -H "Authorization: Bearer pp_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"projectId":"proj_123","metricId":"custom_sales","value":5000}' \
  https://api.dashtray.com/v1/metrics/custom

Best Practices

Security

Never commit API keys: Use environment variables
Rotate keys regularly: Create new keys periodically
Use HTTPS only: Never send keys over HTTP
Limit key scope: Create separate keys for different purposes
Monitor usage: Check API key usage in Settings

Performance

Cache responses: Cache data when appropriate
Use pagination: Don’t fetch all data at once
Batch requests: Combine multiple metric IDs in one request
Respect rate limits: Implement exponential backoff
Use webhooks: Push custom metrics instead of polling

Error Handling

Check status codes: Handle different error types appropriately
Implement retries: Retry failed requests with backoff
Log errors: Track API errors for debugging
Handle rate limits: Wait before retrying when rate limited
Validate input: Check parameters before making requests

Webhooks for Custom Metrics

Use Cases

Push metrics from internal systems
Integrate with tools without native integrations
Send real-time data to Dashtray
Build custom data pipelines

Example: Sending Sales Data

const axios = require('axios');

async function sendSalesMetric(amount) {
  await axios.post('https://api.dashtray.com/v1/metrics/custom', {
    projectId: 'proj_123',
    metricId: 'daily_sales',
    value: amount,
    unit: 'USD',
    metadata: {
      source: 'pos_system',
      location: 'store_1'
    }
  }, {
    headers: {
      'Authorization': 'Bearer pp_your_api_key',
      'Content-Type': 'application/json'
    }
  });
}

// Send daily sales total
sendSalesMetric(15000);

FAQ

Q: How do I get my project ID? A: Go to Settings → General. Your project ID is displayed at the top. Q: Can I create API keys for specific dashboards? A: Not in the MVP. API keys have project-level access. Q: What’s the maximum request size? A: 1MB per request. Q: Can I delete metrics via API? A: No. Metrics are immutable. You can only create new metrics. Q: How long are metrics retained? A: Based on your plan (3 days for Free, unlimited for Pro+). Q: Can I use the API on the Pro plan? A: No. API access requires Scale or Agency plan. Q: Is there a sandbox environment? A: Not in the MVP. Test with a separate project. Q: Can I get real-time data? A: Data is as fresh as your sync frequency (every 30 minutes for Scale+).

Need Help?

Email: support@dashtray.com
API Status: status.dashtray.com/api
Community: Join our Discord for API discussions
Report Issues: github.com/dashtray/api-issues

Getting Started

User Guide

Features

Quickstart Guides

Integrations

API Reference

Technical

Api documentation

API Documentation (Scale+ Only)

Overview

Base URL

Authentication

API Keys

Using API Keys

Example Request

Rate Limiting

Rate Limit Exceeded

Endpoints

GET /metrics

GET /metrics/:metricId/timeseries

GET /dashboards

GET /dashboards/:dashboardId

POST /metrics/custom

Error Responses

Common Error Codes

Code Examples

JavaScript/Node.js

Python

cURL

Best Practices

Security

Performance

Error Handling

Webhooks for Custom Metrics

Use Cases

Example: Sending Sales Data

FAQ

Need Help?

Getting Started

User Guide

Features

Quickstart Guides

Integrations

API Reference

Technical

​API Documentation (Scale+ Only)

​Overview

​Base URL

​Authentication

​API Keys

​Using API Keys

​Example Request

​Rate Limiting

​Rate Limit Exceeded

​Endpoints

​GET /metrics

​GET /metrics/:metricId/timeseries

​GET /dashboards

​GET /dashboards/:dashboardId

​POST /metrics/custom

​Error Responses

​Common Error Codes

​Code Examples

​JavaScript/Node.js

​Python

​cURL

​Best Practices

​Security

​Performance

​Error Handling

​Webhooks for Custom Metrics

​Use Cases

​Example: Sending Sales Data

​FAQ

​Need Help?

API Documentation (Scale+ Only)

Overview

Base URL

Authentication

API Keys

Using API Keys

Example Request

Rate Limiting

Rate Limit Exceeded

Endpoints

GET /metrics

GET /metrics/:metricId/timeseries

GET /dashboards

GET /dashboards/:dashboardId

POST /metrics/custom

Error Responses

Common Error Codes

Code Examples

JavaScript/Node.js

Python

cURL

Best Practices

Security

Performance

Error Handling

Webhooks for Custom Metrics

Use Cases

Example: Sending Sales Data

FAQ

Need Help?