--- title: "Get Workspace Usage Current" method: GET path: "/api/v1/workspace/usage/current" tags: ["workspace"] --- # Get Workspace Usage Current `GET /api/v1/workspace/usage/current` ## Request - Base URL: `https://memory.kagura-ai.com` (the document declares no server; this is the origin it was published from) - URL: `https://memory.kagura-ai.com/api/v1/workspace/usage/current` - Auth: none declared Get workspace-wide usage vs plan limits. Counts are workspace-scoped (#1946): every live memory of the workspace, whoever wrote it, and nothing from members' other workspaces. Returns: Workspace usage statistics with plan limits and warning flags Raises: HTTPException: 400 if no workspace selected, 500 on error ## Headers - `authorization` string, nullable ## Response `200` Successful Response - UsageCurrentResponse: Current usage vs limits response. - `plan` PlanLimits, required: Plan limits and quotas. Issue #198: ``daily_api_limit`` / ``weekly_api_limit`` are the sums of every API tier (MCP + REST + Public) so the dashboard's "API Calls Today" card stays meaningful when looking at the aggregate. Use the per-tier fields below for accurate breakdowns that match ``plan_tiers.py``. Public callers and the rate limiter should always read the per-tier fields, never the legacy combined sums. - `plan_name` string, required: Plan tier key: free | basic | pro | promax - `memory_limit` integer, required: Maximum memories allowed - `daily_total_limit` integer, required: Combined daily limit (MCP + REST + Public) - `weekly_total_limit` integer, required: Combined weekly limit (MCP + REST + Public) - `mcp_calls_per_day` integer: MCP API daily limit - `mcp_calls_per_week` integer: MCP API weekly limit - `rest_calls_per_day` integer: REST API daily limit - `rest_calls_per_week` integer: REST API weekly limit - `public_calls_per_day` integer: Public REST API daily limit - `public_calls_per_week` integer: Public REST API weekly limit - `memories_per_day` integer: Memories that may be created per UTC day (Issue #1549) - `usage` CurrentUsage, required: Current usage statistics. - `memory_count` integer, required: Current memory count - `api_calls_today` integer, required: API calls today (all APIs) - `api_calls_this_week` integer, required: API calls this week (all APIs) - `mcp_calls_today` integer: MCP calls today - `mcp_calls_this_week` integer: MCP calls this week - `rest_calls_today` integer: REST API calls today (non-public) - `rest_calls_this_week` integer: REST API calls this week (non-public) - `public_calls_today` integer: Public REST API calls today - `public_calls_this_week` integer: Public REST API calls this week - `memories_created_today` integer: Memories created today, UTC (Issue #1549 daily quota counter) - `analysis` AnalysisUsage: Memory Analysis daily quota usage (Issue #496). Mirrors the response detail shape of the 429 quota-exceeded body so the dashboard, the new-analysis modal (#497), and the gate rejection all read the same field names. - `used_today` integer: Analyses started today (all statuses count) - `limit_today` integer: Plan + addon daily limit - `addon_bonus` integer: Addon-supplied bonus (extra_analysis_runs) - `remaining_today` integer: max(0, limit_today - used_today) - `resets_at` string, required: ISO-8601 timestamp of the next reset, in the caller's timezone (midnight of the next day). Always populated — the builder falls back to UTC when User.timezone is unset. - `sleep_contexts` SleepContextsUsage: Sleep-enabled contexts quota usage (Issue #560). This is the dashboard READ shape — ``used`` / ``limit`` / ``remaining`` for showing "X / Y" in the UI. The 429 quota-exceeded body raised by ``ContextService._assert_sleep_quota_or_raise`` uses a parallel-but- distinct shape (``current`` / ``requested`` / ``limit`` / ``addon_bonus``) optimized for the action-rejection case ("you tried to enable one more, here's the new total"). Both surfaces share ``limit`` and ``addon_bonus``; the read surface adds ``remaining`` (= ``max(0, limit - used)``) for direct display, and the error surface adds ``requested`` (= ``current + 1``) for "how many would there be." Kept distinct so neither has to carry fields it does not need. - `used` integer: Contexts with sleep_mode != 'skip' in this workspace - `limit` integer: Plan + addon effective limit - `addon_bonus` integer: Addon-supplied bonus (extra_sleep_contexts) - `remaining` integer: max(0, limit - used) - `workspaces` WorkspacesUsage, required: Owned-workspace cap usage (Issue #661). User-level — the cap is per-user, not per-workspace. The dashboard surfaces this so users can see "X / N workspaces owned" before hitting the cap on workspace creation. Unlike ``AnalysisUsage`` / ``SleepContextsUsage``, this field is populated regardless of which workspace the caller currently has selected — it is the user's own quota across all their owned workspaces. No ``addon_bonus`` field as of Issue #661 because there is no per-user addon SKU. If ``addon_workspace_bonus`` (or equivalent) is introduced — see the Out-of-scope section of #661 — add ``addon_bonus`` here to match ``SleepContextsUsage`` / ``AnalysisUsage`` shape. - `used` integer: Owned workspaces (deleted_at IS NULL) - `limit` integer: Effective cap: 1 (base) + users.workspace_slot_bonus (#675) - `remaining` integer: max(0, limit - used) - `memory_usage` UsageStatus, required: Usage status with percentage. - `current` union, required: Current value - integer - number - `limit` union, required: Limit value - integer - number - `percentage` number, required: Usage percentage (0-100+) - `is_warning` boolean, required: True if >= 80% - `is_critical` boolean, required: True if >= 95% - `is_exceeded` boolean, required: True if >= 100% - `daily_api_usage` UsageStatus, required: Usage status with percentage. - `current` union, required: Current value - integer - number - `limit` union, required: Limit value - integer - number - `percentage` number, required: Usage percentage (0-100+) - `is_warning` boolean, required: True if >= 80% - `is_critical` boolean, required: True if >= 95% - `is_exceeded` boolean, required: True if >= 100% - `weekly_api_usage` UsageStatus, required: Usage status with percentage. - `current` union, required: Current value - integer - number - `limit` union, required: Limit value - integer - number - `percentage` number, required: Usage percentage (0-100+) - `is_warning` boolean, required: True if >= 80% - `is_critical` boolean, required: True if >= 95% - `is_exceeded` boolean, required: True if >= 100% - `memories_today_usage` UsageStatus: Usage status with percentage. - `current` union, required: Current value - integer - number - `limit` union, required: Limit value - integer - number - `percentage` number, required: Usage percentage (0-100+) - `is_warning` boolean, required: True if >= 80% - `is_critical` boolean, required: True if >= 95% - `is_exceeded` boolean, required: True if >= 100% - `capacity_lock` CapacityLockInfo: A Free workspace over its plan capacity (#1941). While present, search and saving are refused with ``CAPACITY-001``; listing, deleting and export keep working. ``over_*`` is 0 on an axis that is within its limit. - `memory_count` integer, required: Live memories in the workspace - `memory_limit` integer, required: Effective memory limit - `over_memories` integer, required: Memories to remove to unlock - `used_bytes` integer, required: File bytes the owner can still delete: uploaded, not soft-deleted files that are workspace-scoped or in a live context (#1961) — the figure downgrade-eligibility shares - `storage_limit_bytes` integer, required: Effective storage limit in bytes - `over_bytes` integer, required: File bytes to remove to unlock - `cleanup_url` string, required: Web page to clean up or re-subscribe - `purge_at` string, nullable: When the workspace's memories, contexts and files are deleted if it is still over capacity (#1969): the 04:00 UTC daily sweep 30 days after that sweep first saw it over, ISO-8601 UTC. Null until that sweep has run, and while the purge is disabled on this deployment (CAPACITY_PURGE_ENABLED). ## Other responses - `422`: Validation Error --- [API](https://skmtc.dev/kagura-ai/apis/kagura-memory-cloud.md) · [All operations](https://skmtc.dev/kagura-ai/apis/kagura-memory-cloud/llms.txt) · [OpenAPI document](https://skmtc.dev/kagura-ai/apis/kagura-memory-cloud/revisions/09f17f5ada29?raw)