Billing API

The Billing API provides budget management, cost tracking, and usage analytics. Control spending with configurable limits and monitor costs by agent, environment, or time period.

Budget System

Each user has a budget with:

Starting balance: $10.00 (free tier)
Daily limit: Configurable
Monthly limit: Configurable

Budget is checked before every execution. HTTP 402 is returned when budget is exhausted.

Get User Budget


GET /v1/billing/budget

Example


curl https://api.computer-agents.com/v1/billing/budget \
  -H "Authorization: Bearer $API_KEY"

Response


{
  "userId": "user_xxx",
  "balance": 8.50,
  "totalSpent": 1.50,
  "dailyLimit": null,
  "monthlyLimit": 100.00,
  "dailySpent": 0.75,
  "monthlySpent": 1.50,
  "createdAt": "2025-01-01T00:00:00Z",
  "updatedAt": "2025-01-15T10:00:00Z"
}

Attributes

Attribute	Type	Description
`balance`	number	Current available balance
`totalSpent`	number	All-time spending
`dailyLimit`	number	Daily spending limit (null = unlimited)
`monthlyLimit`	number	Monthly spending limit (null = unlimited)
`dailySpent`	number	Amount spent today
`monthlySpent`	number	Amount spent this month

Get Billing Records

View transaction history.


GET /v1/billing/records

Query Parameters

Parameter	Type	Default	Description
`from`	string	-	Start date (ISO 8601)
`to`	string	-	End date (ISO 8601)
`limit`	number	50	Max results
`offset`	number	0	Pagination offset

Example


curl "https://api.computer-agents.com/v1/billing/records?limit=10" \
  -H "Authorization: Bearer $API_KEY"

Response


{
  "object": "list",
  "data": [
    {
      "id": "rec_xxx",
      "recordType": "charge",
      "amount": 0.015,
      "description": "Thread execution: Build REST API",
      "threadId": "thread_xxx",
      "createdAt": "2025-01-15T10:30:00Z"
    },
    {
      "id": "rec_yyy",
      "recordType": "credit",
      "amount": 10.00,
      "description": "Initial credit",
      "createdAt": "2025-01-01T00:00:00Z"
    }
  ],
  "has_more": true,
  "total_count": 156
}

Record Types

Type	Description
`charge`	Execution cost deduction
`credit`	Credit added (purchase, promo, admin)
`refund`	Refund for failed execution

Cost Summary

Get aggregated cost data for a time period.


GET /v1/billing/costs/summary

Query Parameters

Parameter	Type	Default	Description
`period`	string	`month`	`day`, `week`, `month`, `year`, `all`
`startDate`	string	-	Custom start (ISO 8601)
`endDate`	string	-	Custom end (ISO 8601)

Example


curl "https://api.computer-agents.com/v1/billing/costs/summary?period=month" \
  -H "Authorization: Bearer $API_KEY"

Response


{
  "period": "month",
  "startDate": "2025-01-01T00:00:00Z",
  "endDate": "2025-01-31T23:59:59Z",
  "totals": {
    "totalCost": 45.50,
    "agentCost": 38.00,
    "environmentCost": 7.50,
    "totalThreads": 125,
    "inputTokens": 2500000,
    "outputTokens": 1250000
  },
  "byDay": [
    {
      "date": "2025-01-15",
      "totalCost": 2.50,
      "agentCost": 2.00,
      "environmentCost": 0.50,
      "threadCount": 5,
      "inputTokens": 50000,
      "outputTokens": 25000
    }
  ]
}

Cost Breakdown

Get costs grouped by agent or environment.


GET /v1/billing/costs/breakdown

Query Parameters

Parameter	Type	Default	Description
`groupBy`	string	`agent`	`agent` or `environment`
`period`	string	`month`	Time period
`startDate`	string	-	Custom start
`endDate`	string	-	Custom end

Example: By Agent


curl "https://api.computer-agents.com/v1/billing/costs/breakdown?groupBy=agent" \
  -H "Authorization: Bearer $API_KEY"

Response


{
  "groupBy": "agent",
  "period": "month",
  "data": [
    {
      "id": "agent_xxx",
      "name": "Code Assistant",
      "totalCost": 25.00,
      "agentCost": 22.00,
      "environmentCost": 3.00,
      "threadCount": 80
    },
    {
      "id": "agent_yyy",
      "name": "Reviewer",
      "totalCost": 13.00,
      "agentCost": 11.00,
      "environmentCost": 2.00,
      "threadCount": 45
    }
  ]
}

Example: By Environment


curl "https://api.computer-agents.com/v1/billing/costs/breakdown?groupBy=environment" \
  -H "Authorization: Bearer $API_KEY"

Thread Costs

Get cost details for individual threads.


GET /v1/billing/costs/threads

Query Parameters

Parameter	Type	Default	Description
`limit`	number	50	Max results
`offset`	number	0	Pagination offset
`sortBy`	string	`createdAt`	`totalCost`, `agentCost`, `createdAt`, `duration`
`order`	string	`desc`	`asc` or `desc`
`startDate`	string	-	Filter start
`endDate`	string	-	Filter end
`agentId`	string	-	Filter by agent
`environmentId`	string	-	Filter by environment

Example


curl "https://api.computer-agents.com/v1/billing/costs/threads?sortBy=totalCost&order=desc&limit=10" \
  -H "Authorization: Bearer $API_KEY"

Response


{
  "object": "list",
  "data": [
    {
      "threadId": "thread_xxx",
      "title": "Build REST API",
      "agentId": "agent_xxx",
      "agentName": "Code Assistant",
      "environmentId": "env_xxx",
      "totalCost": 1.25,
      "agentCost": 1.00,
      "environmentCost": 0.25,
      "inputTokens": 15000,
      "outputTokens": 8000,
      "duration": 45,
      "createdAt": "2025-01-15T10:30:00Z"
    }
  ],
  "has_more": true,
  "total_count": 125
}

Token Usage

Get detailed token usage over time.


GET /v1/billing/costs/tokens

Query Parameters

Parameter	Type	Default	Description
`period`	string	`week`	`day`, `week`, `month`
`startDate`	string	-	Custom start
`endDate`	string	-	Custom end

Example


curl "https://api.computer-agents.com/v1/billing/costs/tokens?period=week" \
  -H "Authorization: Bearer $API_KEY"

Response


{
  "period": "week",
  "byDay": [
    {
      "date": "2025-01-15",
      "inputTokens": 150000,
      "outputTokens": 75000,
      "cacheTokens": 25000,
      "totalTokens": 225000
    }
  ],
  "totals": {
    "inputTokens": 1050000,
    "outputTokens": 525000,
    "cacheTokens": 175000,
    "totalTokens": 1575000
  }
}

Pricing

Current token pricing:

Token Type	Price per 1M tokens
Input tokens	$2.50
Output tokens	$10.00
Cache tokens	$0.25

Prices may vary by model. Check your dashboard for current rates.

Budget Enforcement

The API checks budget before execution:

Balance check - Do you have enough balance?
Daily limit check - Would this exceed daily limit?
Monthly limit check - Would this exceed monthly limit?

If any check fails, HTTP 402 is returned:


{
  "error": "Payment Required",
  "message": "Insufficient budget to execute",
  "budgetStatus": {
    "balance": 0.50,
    "dailyLimit": 10.00,
    "dailySpent": 9.80,
    "monthlyLimit": 100.00,
    "monthlySpent": 85.00
  }
}

Budget Error Handling

Handle 402 errors gracefully:


try {
  await executeTask(task);
} catch (error) {
  if (error.status === 402) {
    const { budgetStatus } = error.data;
 
    if (budgetStatus.balance < 1) {
      showAddCreditsPrompt();
    } else if (budgetStatus.dailySpent >= budgetStatus.dailyLimit) {
      showDailyLimitReachedMessage();
    } else {
      showMonthlyLimitReachedMessage();
    }
  }
}

Adding Credits

Credits can be added via:

LemonSqueezy payments - Webhook automatically adds credits
Admin API - For enterprise/custom arrangements

Cost Optimization Tips

Use caching - Repeated queries benefit from token caching
Optimize prompts - Shorter, focused prompts reduce input costs
Choose appropriate models - Use smaller models for simple tasks
Set budget limits - Prevent unexpected costs with daily/monthly limits
Monitor by agent - Identify expensive agents and optimize

Threads - Execution costs per thread
Error Handling - Handle 402 budget errors

Billing API

Budget System

Get User Budget

Example

Response

Attributes

Get Billing Records

Query Parameters

Example

Response

Record Types

Cost Summary

Query Parameters

Example

Response

Cost Breakdown

Query Parameters

Example: By Agent

Response

Example: By Environment

Thread Costs

Query Parameters

Example

Response

Token Usage

Query Parameters

Example

Response

Pricing

Budget Enforcement

Budget Error Handling

Adding Credits

Cost Optimization Tips

Related