Usage & Activity

Track resource consumption over time - CPU, memory, disk I/O, and network. Usage data is compacted into tiers for efficient querying across different time ranges.

Global usage

Get aggregated usage across all your workspaces.

const usage = await ws.usage.global();

GET /workspace/usage

curl "https://api.oblien.com/workspace/usage" \
  -H "X-Client-ID: $OBLIEN_CLIENT_ID" \
  -H "X-Client-Secret: $OBLIEN_CLIENT_SECRET"

Response

{
  "success": true,
  "usage": {
    "ws_a1b2c3d4": {
      "total_cpu_time_ns": 1200000000,
      "total_disk_read": 52428800,
      "total_disk_write": 10485760,
      "total_net_rx": 1258291,
      "total_net_tx": 524288
    }
  },
  "total": {
    "total_cpu_time_ns": 3600000000,
    "total_disk_read": 104857600,
    "total_disk_write": 20971520,
    "total_net_rx": 5242880,
    "total_net_tx": 2097152
  }
}

Activity

Get historical activity data across all workspaces.

const activity = await ws.activity({
  from: '2026-02-01T00:00:00Z',
  to: '2026-02-24T23:59:59Z',
});

GET /workspace/activity?from=2026-02-01T00:00:00Z&to=2026-02-24T23:59:59Z

curl "https://api.oblien.com/workspace/activity?from=2026-02-01T00:00:00Z&to=2026-02-24T23:59:59Z" \
  -H "X-Client-ID: $OBLIEN_CLIENT_ID" \
  -H "X-Client-Secret: $OBLIEN_CLIENT_SECRET"

Query parameters

Parameter	Type	Description
`from`	`string`	Start time (ISO 8601)
`to`	`string`	End time (ISO 8601)

Response

{
  "success": true,
  "from": "2026-02-01T00:00:00Z",
  "to": "2026-02-24T23:59:59Z",
  "history": {},
  "window_aggregated": {}
}

Workspace usage

Get detailed usage for a single workspace with time-series data.

// By time range
const usage = await ws.usage.get('ws_a1b2c3d4', {
  from: '2026-02-24T00:00:00Z',
  to: '2026-02-24T23:59:59Z',
});

// By shorthand
const recent = await ws.usage.get('ws_a1b2c3d4', { last: '1h' });

// By tier
const detailed = await ws.usage.get('ws_a1b2c3d4', { tier: 0 });

// Get everything
const all = await ws.usage.get('ws_a1b2c3d4', { all: true });

GET /workspace/:workspaceId/usage?last=1h
GET /workspace/:workspaceId/usage?from=...&to=...
GET /workspace/:workspaceId/usage?tier=0
GET /workspace/:workspaceId/usage?all=true

curl "https://api.oblien.com/workspace/ws_a1b2c3d4/usage?last=1h" \
  -H "X-Client-ID: $OBLIEN_CLIENT_ID" \
  -H "X-Client-Secret: $OBLIEN_CLIENT_SECRET"

Query parameters

Parameter	Type	Description
`from`	`string`	Start time (ISO 8601)
`to`	`string`	End time (ISO 8601)
`tier`	`number`	Specific data tier (0–5)
`last`	`string`	Time shorthand: `"1h"`, `"6h"`, `"3d"`, etc.
`all`	`string`	`"true"` to fetch all data

Data tiers

Usage data is automatically compacted into resolution tiers:

Tier	Window	Resolution	Use case
0	Last 2 min	1 second	Real-time dashboard
1	2–15 min	10 seconds	Recent activity
2	15 min – 1 hour	1 minute	Hourly view
3	1–6 hours	10 minutes	Day view
4	6 hours – 3 days	1 hour	Week view
5	3–90 days	24 hours	Historical view

Totals

Get aggregated totals for a workspace.

const totals = await ws.usage.totals('ws_a1b2c3d4');

GET /workspace/:workspaceId/usage/totals

curl "https://api.oblien.com/workspace/ws_a1b2c3d4/usage/totals" \
  -H "X-Client-ID: $OBLIEN_CLIENT_ID" \
  -H "X-Client-Secret: $OBLIEN_CLIENT_SECRET"

Credits chart

Get time-bucketed credit consumption data optimized for charting. Returns up to 7 data points with auto-selected granularity.

const chart = await ws.usage.creditsChart('ws_a1b2c3d4');

chart.data.forEach(point => {
  console.log(`${point.date}: ${point.creditsBurned} credits`);
});
console.log(`Total: ${chart.total} credits`);

GET /workspace/:workspaceId/usage/credits/chart

curl "https://api.oblien.com/workspace/ws_a1b2c3d4/usage/credits/chart" \
  -H "X-Client-ID: $OBLIEN_CLIENT_ID" \
  -H "X-Client-Secret: $OBLIEN_CLIENT_SECRET"

Response

{
  "success": true,
  "granularity": "hour",
  "data": [
    { "date": "2026-02-24T08:00:00Z", "creditsBurned": 12.5 },
    { "date": "2026-02-24T09:00:00Z", "creditsBurned": 8.3 },
    { "date": "2026-02-24T10:00:00Z", "creditsBurned": 15.7 }
  ],
  "total": 36.5
}

Granularity auto-scales: minute → hour → day depending on the data range. Results are cached for 60 seconds.

Start tracking

Enable usage tracking for a workspace.

await ws.usage.startTracking('ws_a1b2c3d4');

POST /workspace/:workspaceId/usage/tracking/start

curl -X POST "https://api.oblien.com/workspace/ws_a1b2c3d4/usage/tracking/start" \
  -H "X-Client-ID: $OBLIEN_CLIENT_ID" \
  -H "X-Client-Secret: $OBLIEN_CLIENT_SECRET"

Stop tracking

Disable usage tracking for a workspace.

await ws.usage.stopTracking('ws_a1b2c3d4');

POST /workspace/:workspaceId/usage/tracking/stop

curl -X POST "https://api.oblien.com/workspace/ws_a1b2c3d4/usage/tracking/stop" \
  -H "X-Client-ID: $OBLIEN_CLIENT_ID" \
  -H "X-Client-Secret: $OBLIEN_CLIENT_SECRET"

Wipe usage data

Delete all usage data for a workspace. This action is irreversible.

await ws.usage.wipe('ws_a1b2c3d4');

DELETE /workspace/:workspaceId/usage

curl -X DELETE "https://api.oblien.com/workspace/ws_a1b2c3d4/usage" \
  -H "X-Client-ID: $OBLIEN_CLIENT_ID" \
  -H "X-Client-Secret: $OBLIEN_CLIENT_SECRET"

On this page