Usage API

Authentication Required: All usage endpoints require the X-API-Key header.

Summary, analytics, sessions, and events are automatically scoped by the caller role. Account root users review team quota requests through the account-management endpoints, while non-root users use /v1/usage/quota-requests.

Response Conventions

Usage APIs use the standard envelope:

{
  "success": true,
  "data": {},
  "timestamp": "2026-04-20T12:34:56Z"
}

List endpoints return data.<items> plus data.pagination:

{
  "success": true,
  "data": {
    "sessions": [],
    "pagination": {
      "page": 1,
      "limit": 50,
      "total": 0,
      "total_pages": 0,
      "offset": 0
    }
  },
  "timestamp": "2026-04-20T12:34:56Z"
}

Real pagination params are page plus limit (or alias page_size).

Endpoints

Get Usage Summary

GET /v1/usage/summary

Query parameters:

Name	Type	Required	Description
start	RFC3339 datetime	No	Start of the range. Defaults to the last 30 days.
end	RFC3339 datetime	No	End of the range. Defaults to now.
project_id	string	No	Optional project filter.

Returns data.summary and data.time_period.

{
  "success": true,
  "data": {
    "summary": {
      "total_sessions": 18,
      "active_sessions": 2,
      "completed_sessions": 15,
      "failed_sessions": 1,
      "total_cpu_hours": 34.5,
      "total_memory_gb_hours": 96.0,
      "total_storage_gb_hours": 140.25,
      "avg_session_duration": 4180,
      "total_cost": 12.84
    },
    "time_period": {
      "start": "2026-04-01T00:00:00Z",
      "end": "2026-04-20T00:00:00Z"
    }
  },
  "timestamp": "2026-04-20T12:34:56Z"
}

Get Usage Analytics

GET /v1/usage/analytics

Query parameters: start, end.

Returns data.summary plus chart-oriented arrays under data.charts:

sessions_over_time
resource_utilization
cost_breakdown

List Usage Sessions

GET /v1/usage/sessions

Query parameters:

Name	Type	Required	Description
page	integer	No	Page number, default `1`.
limit	integer	No	Page size, default `50`.
page_size	integer	No	Alias for `limit`.
start	RFC3339 datetime	No	Optional lower bound for `start_time`.
end	RFC3339 datetime	No	Optional upper bound for `start_time`.

Response:

{
  "success": true,
  "data": {
    "sessions": [
      {
        "session_id": "ses_01HXYZ...",
        "resource_type": "sandbox",
        "resource_id": "sbx-1234567890ab",
        "resource_name": "python-dev",
        "status": "completed",
        "start_time": "2026-04-19T09:00:00Z",
        "end_time": "2026-04-19T10:15:00Z",
        "duration": 4500,
        "cpu_count": 2,
        "memory_mb": 4096,
        "storage_gb": 20,
        "estimated_cost": 1.42,
        "final_cost": 1.39
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 50,
      "total": 1,
      "total_pages": 1,
      "offset": 0
    }
  },
  "timestamp": "2026-04-20T12:34:56Z"
}

List Usage Events

GET /v1/usage/events

Query parameters:

Name	Type	Required	Description
page	integer	No	Page number, default `1`.
limit	integer	No	Page size, default `50`.
page_size	integer	No	Alias for `limit`.
start	RFC3339 datetime	No	Optional lower bound for `event_timestamp`.
end	RFC3339 datetime	No	Optional upper bound for `event_timestamp`.
project_id	string	No	Optional project filter.
resource_type	string	No	Optional resource type filter.
usage_type	string	No	Optional event type filter.
account_id	string	No	Admin-only account filter.

Response:

{
  "success": true,
  "data": {
    "events": [
      {
        "event_id": "evt-1234567890",
        "resource_type": "sandbox",
        "resource_id": "sbx-1234567890ab",
        "user_id": "usr-1234567890ab",
        "account_id": "acc-123456789",
        "project_id": "prj-1234567890ab",
        "usage_type": "sandbox.started",
        "usage_quantity": 1,
        "usage_unit": "event",
        "resource_specs": {
          "cpu_count": 2,
          "memory_mb": 4096
        },
        "event_timestamp": "2026-04-19T09:00:00Z",
        "period_start": "2026-04-19T09:00:00Z",
        "period_end": "2026-04-19T10:15:00Z",
        "unit_price": 0.05,
        "total_cost": 1.39,
        "currency": "USD",
        "metadata": {},
        "tags": {},
        "created_at": "2026-04-19T10:15:03Z"
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 50,
      "total": 1,
      "total_pages": 1,
      "offset": 0
    }
  },
  "timestamp": "2026-04-20T12:34:56Z"
}

Get Effective Quotas

GET /v1/usage/quotas

Returns the caller's active user quota allocation, or data.quotas: null when no allocation exists.

{
  "success": true,
  "data": {
    "quotas": {
      "allocation_id": "qal-1234567890ab",
      "account_id": "acc-123456789",
      "user_id": "usr-1234567890ab",
      "cpu_seconds_monthly": 500000,
      "ram_gb_seconds": 1200000,
      "sandbox_storage_gb_seconds": 2400000,
      "traffic_gb_seconds": 50000,
      "template_storage_gb": 50,
      "concurrent_sandboxes": 3,
      "status": "active",
      "created_at": "2026-04-01T00:00:00Z",
      "updated_at": "2026-04-15T08:00:00Z"
    }
  },
  "timestamp": "2026-04-20T12:34:56Z"
}

Manage My Quota Requests

Non-root users can manage their own requests with these endpoints:

GET /v1/usage/quota-requests
POST /v1/usage/quota-requests
PUT /v1/usage/quota-requests/{request_id}
DELETE /v1/usage/quota-requests/{request_id}

Request body fields for create and update:

Name	Type	Required	Description
cpu_seconds_monthly	int64	Yes	Monthly CPU allocation request.
ram_gb_seconds	number	No	Requested RAM GB-seconds.
sandbox_storage_gb_seconds	number	No	Requested sandbox storage GB-seconds.
traffic_gb_seconds	number	No	Requested traffic GB-seconds.
template_storage_gb	number	Yes	Requested template storage in GB.
concurrent_sandboxes	integer	No	`0` means unlimited at user level.
reason	string	Yes	Human review reason.

List query parameters:

Name	Type	Required	Description
status	string	No	Filter by request status such as `pending`, `approved`, `denied`, or `withdrawn`.
page	integer	No	Page number.
limit	integer	No	Page size.
page_size	integer	No	Alias for `limit`.

List response:

{
  "success": true,
  "data": {
    "requests": [
      {
        "request_id": "qtr-1234567890ab",
        "user_id": "usr-1234567890ab",
        "account_id": "acc-123456789",
        "cpu_seconds_monthly": 750000,
        "ram_gb_seconds": 1800000,
        "sandbox_storage_gb_seconds": 3200000,
        "traffic_gb_seconds": 100000,
        "template_storage_gb": 100,
        "concurrent_sandboxes": 5,
        "reason": "Need more headroom for CI workloads",
        "status": "pending",
        "reviewed_by": null,
        "reviewed_at": null,
        "review_notes": null,
        "created_at": "2026-04-18T08:00:00Z",
        "updated_at": "2026-04-18T08:00:00Z"
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 50,
      "total": 1,
      "total_pages": 1,
      "offset": 0
    }
  },
  "timestamp": "2026-04-20T12:34:56Z"
}

Usage API

On this page