Skip to content

feat: implement usage & spending API client #981

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
pec1985 wants to merge 4 commits into from
Closed

feat: implement usage & spending API client #981

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
1b7050c
feat: implement usage & spending API client
pec1985 Feb 17, 2026
6b30df3
test: add unit and integration tests for usage API
pec1985 Feb 17, 2026
85ce71e
docs: update AGENTS.md with usage API documentation
pec1985 Feb 17, 2026
39e1b0a
removed unsused imports
pec1985 Feb 17, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 11 additions & 1 deletion packages/server/AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -38,6 +38,7 @@ src/
├── sandbox/ # Sandbox management (create, execute, files, snapshot)
├── session/ # Session logs
├── thread/ # Thread management
├── usage/ # Usage & spending tracking
└── user/ # User operations (whoami)
```

Expand All @@ -54,7 +55,16 @@ src/
- **Config**: `getServiceUrls`, `resolveRegion`
- **Logging**: `createLogger`, `ConsoleLogger`
- **Validation**: `validateResources`, `validateCPUSpec`, `validateMemorySpec`
- **API Clients**: All functions from `api/*` (listProjects, createSandbox, etc.)
- **API Clients**: All functions from `api/*` (listProjects, createSandbox, getUsageSummary, etc.)

## Key APIs by Module

### Usage & Spending Tracking

- **Zero-config**: `getUsageSummary()`, `getUsageBreakdown()`, `getUsageTimeseries()`
- Auto-resolves API client and project ID from environment when running in Agentuity
- Provides cost metrics, token usage, and session counts
- Supports time-series data, grouping by agent/deployment/day/hour
Comment on lines +60 to +67
Copy link
Copy Markdown
Contributor

@coderabbitai coderabbitai Bot Feb 17, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor

Documentation depth inconsistency.

The section title "Key APIs by Module" (plural) suggests comprehensive coverage of multiple modules, but currently only the Usage & Spending Tracking module is documented. Other established modules listed in the structure (apikey, db, eval, org, project, queue, region, sandbox, session, thread, user) lack similar detailed documentation.

Consider one of these approaches:

  1. Add brief documentation for other key modules to create consistency
  2. Rename the section to be more specific (e.g., "### Usage & Spending Tracking API") and remove the "## Key APIs by Module" parent section
📝 Proposed fix: Make section title more specific 
-## Key APIs by Module
-
-### Usage & Spending Tracking
+## Usage & Spending Tracking
 
 - **Zero-config**: `getUsageSummary()`, `getUsageBreakdown()`, `getUsageTimeseries()`
 - Auto-resolves API client and project ID from environment when running in Agentuity

Note: The actual content documenting the Usage API is accurate and helpful. This comment only addresses the structural inconsistency in documentation organization.

🤖 Prompt for AI Agents 
Verify each finding against the current code and only fix it if needed.

In `@packages/server/AGENTS.md` around lines 60 - 67, The top-level heading "##
Key APIs by Module" implies multiple modules but only "### Usage & Spending
Tracking" is documented; fix by either (A) expanding this section to add brief
API summaries for the other modules listed (apikey, db, eval, org, project,
queue, region, sandbox, session, thread, user) matching the style of
getUsageSummary/getUsageBreakdown/getUsageTimeseries, or (B) rename "## Key APIs
by Module" to a specific heading such as "### Usage & Spending Tracking API" and
remove the plural parent section; update the header text for "## Key APIs by
Module" and/or the "### Usage & Spending Tracking" heading accordingly so the
document structure is consistent.


## Publishing

Expand Down
1 change: 1 addition & 0 deletions packages/server/src/api/index.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,4 +11,5 @@ export * from './sandbox';
export * from './session';
export * from './stream';
export * from './thread';
export * from './usage';
Copy link
Copy Markdown
Contributor

@coderabbitai coderabbitai Bot Feb 17, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor

Replace the wildcard usage export with named exports.

The new wildcard export adds another index.ts export * despite the named-export requirement. Please re-export explicit names from ./usage (mirroring the list in packages/server/src/api/usage/index.ts). As per coding guidelines: "Use named exports from package index.ts files".

✅ Suggested explicit re-export 
-export * from './usage';
+export {
+	type TokenUsage,
+	TokenUsageSchema,
+	type UsageBreakdown,
+	type UsageBreakdownGroup,
+	UsageBreakdownGroupSchema,
+	type UsageBreakdownOptions,
+	UsageBreakdownSchema,
+	type UsageGranularity,
+	UsageGranularitySchema,
+	type UsageGroupBy,
+	UsageGroupBySchema,
+	type UsageMetric,
+	UsageMetricSchema,
+	type UsageOptions,
+	type UsageSortBy,
+	UsageSortBySchema,
+	type UsageSummary,
+	UsageSummarySchema,
+	type UsageTimeseries,
+	type UsageTimeseriesBucket,
+	UsageTimeseriesBucketSchema,
+	type UsageTimeseriesOptions,
+	UsageTimeseriesSchema,
+	createDefaultClient,
+	UsageError,
+	UsageNotFoundError,
+	getUsageBreakdown,
+	getUsageSummary,
+	getUsageTimeseries,
+	UsageBreakdownResponseSchema,
+	UsageSummaryResponseSchema,
+	UsageTimeseriesResponseSchema,
+} from './usage';
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
export * from './usage';
export {
type TokenUsage,
TokenUsageSchema,
type UsageBreakdown,
type UsageBreakdownGroup,
UsageBreakdownGroupSchema,
type UsageBreakdownOptions,
UsageBreakdownSchema,
type UsageGranularity,
UsageGranularitySchema,
type UsageGroupBy,
UsageGroupBySchema,
type UsageMetric,
UsageMetricSchema,
type UsageOptions,
type UsageSortBy,
UsageSortBySchema,
type UsageSummary,
UsageSummarySchema,
type UsageTimeseries,
type UsageTimeseriesBucket,
UsageTimeseriesBucketSchema,
type UsageTimeseriesOptions,
UsageTimeseriesSchema,
createDefaultClient,
UsageError,
UsageNotFoundError,
getUsageBreakdown,
getUsageSummary,
getUsageTimeseries,
UsageBreakdownResponseSchema,
UsageSummaryResponseSchema,
UsageTimeseriesResponseSchema,
} from './usage';
🤖 Prompt for AI Agents 
Verify each finding against the current code and only fix it if needed.

In `@packages/server/src/api/index.ts` at line 14, Replace the wildcard export in
packages/server/src/api/index.ts with explicit named re-exports that match the
exports declared in packages/server/src/api/usage/index.ts; in other words,
remove "export * from './usage';" and instead re-export each exported identifier
from './usage' (copy the exact export names from the usage/index.ts file) so the
package index uses only named exports.

export * from './user';
103 changes: 103 additions & 0 deletions packages/server/src/api/usage/index.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,103 @@
/**
* @module usage
*
* Usage & Spending API client for querying project-level cost and usage data.
*
* This module provides typed client functions for the Agentuity Usage API,
* which aggregates session cost data by project. It supports:
* - **Summary**: Aggregated cost totals for a project within a time range
* - **Breakdown**: Cost data grouped by agent, deployment, day, or hour
* - **Timeseries**: Time-bucketed usage data for charting and visualization
*
* All costs are in USD. All timestamps are RFC 3339 format.
*
* @example Summary (zero-config)
* ```typescript
* import { getUsageSummary } from '@agentuity/server';
*
* const summary = await getUsageSummary({
* start: '2025-01-01T00:00:00Z',
* end: '2025-02-01T00:00:00Z',
* });
* console.log(`Total cost: $${summary.totalCost}`);
* ```
*
* @example Breakdown (zero-config)
* ```typescript
* import { getUsageBreakdown } from '@agentuity/server';
*
* const breakdown = await getUsageBreakdown({
* start: '2025-01-01T00:00:00Z',
* end: '2025-02-01T00:00:00Z',
* groupBy: 'agent',
* sortBy: 'cost_desc',
* });
* for (const group of breakdown.groups) {
* console.log(`${group.label}: $${group.totalCost}`);
* }
* ```
*
* @example Timeseries (zero-config)
* ```typescript
* import { getUsageTimeseries } from '@agentuity/server';
*
* const timeseries = await getUsageTimeseries({
* start: '2025-01-01T00:00:00Z',
* end: '2025-01-08T00:00:00Z',
* granularity: 'day',
* metrics: ['totalCost', 'sessionCount'],
* });
* for (const bucket of timeseries.buckets) {
* console.log(`${bucket.timestamp}: $${bucket.totalCost}`);
* }
* ```
*/

// ============================================================================
// Types & Schemas
// ============================================================================

export {
type TokenUsage,
TokenUsageSchema,
type UsageBreakdown,
type UsageBreakdownGroup,
UsageBreakdownGroupSchema,
type UsageBreakdownOptions,
UsageBreakdownSchema,
type UsageGranularity,
UsageGranularitySchema,
type UsageGroupBy,
UsageGroupBySchema,
type UsageMetric,
UsageMetricSchema,
type UsageOptions,
type UsageSortBy,
UsageSortBySchema,
type UsageSummary,
UsageSummarySchema,
type UsageTimeseries,
type UsageTimeseriesBucket,
UsageTimeseriesBucketSchema,
type UsageTimeseriesOptions,
UsageTimeseriesSchema,
} from './types';

// ============================================================================
// Errors
// ============================================================================

export { createDefaultClient, UsageError, UsageNotFoundError } from './util';
Copy link
Copy Markdown
Contributor

@coderabbitai coderabbitai Bot Feb 17, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor

Public re-export conflicts with the @internal tag.

createDefaultClient is annotated as @internal in util.ts but is re-exported here; either drop the @internal tag or keep it private to avoid API/documentation confusion.

🤖 Prompt for AI Agents 
Verify each finding against the current code and only fix it if needed.

In `@packages/server/src/api/usage/index.ts` at line 90, The re-export exposes
createDefaultClient (annotated `@internal` in util.ts) causing API/docs mismatch;
either remove createDefaultClient from the public export in index.ts (keep
exporting UsageError and UsageNotFoundError) or remove the `@internal` JSDoc tag
from createDefaultClient in util.ts so it is intentionally public—pick one and
update the export line or the JSDoc accordingly, referencing createDefaultClient
and the export statement in index.ts and the `@internal` tag on
createDefaultClient in util.ts.


// ============================================================================
// Usage Operations
// ============================================================================

export {
getUsageBreakdown,
getUsageSummary,
getUsageTimeseries,
UsageBreakdownResponseSchema,
UsageSummaryResponseSchema,
UsageTimeseriesResponseSchema,
} from './usage';
Loading
Loading