Analytics API

The Analytics API provides insights into workflow and direct execution performance, gas usage, and execution trends across your organization.

Authentication

All analytics routes accept either a session cookie or an organization API key (Authorization: Bearer $KEEPERHUB_API_KEY) except the two that are session-only:

• GET /api/analytics/summary, GET /api/analytics/time-series, GET /api/analytics/networks, GET /api/analytics/runs, and GET /api/analytics/spend-cap accept a kh_ organization key with the mcp:read scope. A legacy key with no scope is admitted (an unscoped key means full access). A session caller carries no scope and is unaffected - the scope gate applies to key callers only.
• GET /api/analytics/stream is session-only: it is a server-sent-events feed consumed by a browser EventSource, which cannot send an Authorization header, so a key has no way to use it.
• GET /api/analytics/runs/{executionId}/steps is session-only: it reads the caller’s organization from the session.

Get Analytics Summary

GET /api/analytics/summary

Returns aggregated analytics for the organization including run counts, success rates, and gas usage.

Query Parameters

Response

{
  "totalRuns": 1250,
  "successfulRuns": 1180,
  "failedRuns": 70,
  "successRate": 94.4,
  "totalGasUsedWei": "15000000000000000",
  "avgExecutionTimeMs": 2340
}

Field Definitions

Get Time Series Data

GET /api/analytics/time-series

Returns time-bucketed run counts for charting execution volume over time.

Query Parameters

Same as summary endpoint.

Response

{
  "buckets": [
    {
      "timestamp": "2024-01-01T00:00:00Z",
      "runCount": 42,
      "successCount": 40,
      "failedCount": 2
    }
  ]
}

Get Network Breakdown

GET /api/analytics/networks

Returns execution counts and gas usage grouped by blockchain network. Gas totals include both workflow executions and direct executions on each network.

Query Parameters

Same as summary endpoint.

Response

{
  "networks": [
    {
      "network": "ethereum",
      "runCount": 520,
      "gasUsedWei": "8000000000000000"
    },
    {
      "network": "base",
      "runCount": 380,
      "gasUsedWei": "2500000000000000"
    }
  ]
}

List Runs

GET /api/analytics/runs

Returns a unified list of both workflow executions and direct executions with pagination.

Query Parameters

Response

{
  "runs": [
    {
      "id": "hjsuassmcb19zvfpzi38r",
      "source": "workflow",
      "workflowId": "y3y0xneior3njl90uoyih",
      "workflowName": "Monitor ETH Balance",
      "status": "success",
      "createdAt": "2024-01-01T00:00:00Z",
      "completedAt": "2024-01-01T00:00:05Z",
      "durationMs": 5000
    },
    {
      "id": "9k2x7mwqcp5zvt0hnj1ab",
      "source": "direct",
      "type": "transfer",
      "network": "ethereum",
      "status": "success",
      "transactionHash": "0x...",
      "gasUsedWei": "21000000000000",
      "createdAt": "2024-01-01T00:01:00Z",
      "completedAt": "2024-01-01T00:01:15Z"
    }
  ],
  "nextCursor": "cursor_abc123"
}

Get Run Step Logs

GET /api/analytics/runs/{executionId}/steps

Returns detailed step-by-step logs for a specific execution.

Response

{
  "steps": [
    {
      "nodeId": "node_1",
      "nodeName": "Trigger",
      "status": "success",
      "input": {...},
      "output": {...},
      "durationMs": 120,
      "timestamp": "2024-01-01T00:00:00Z"
    }
  ]
}

Get Spend Cap Data

GET /api/analytics/spend-cap

Returns current spending status against the daily spending caps.

dailyCapWei and dailySolanaCapLamports report what the organization configured, and are null when it configured nothing. That is not the same as being uncapped: the effective* fields carry the figure enforcement actually applies, which is the platform default whenever usingDefault* is true. Plan against the effective figures.

Response

{
  "dailyCapWei": null,
  "dailyUsedWei": "25000000000000000",
  "dailySolanaCapLamports": null,
  "dailySolanaUsedLamports": "0",
  "effectiveDailyCapWei": "20000000000000000",
  "effectiveDailySolanaCapLamports": "500000000",
  "usingDefaultDailyCap": true,
  "usingDefaultDailySolanaCap": true
}

Stream Analytics (SSE)

GET /api/analytics/stream

Server-Sent Events endpoint for real-time analytics updates.

Query Parameters

Same as summary endpoint.

Event Format

data: {"type":"summary","data":{...}}

data: {"type":"summary","data":{...}}

The stream sends updated summary data every 2 seconds when changes are detected, with automatic reconnection and heartbeat support.