Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/paperclipai/paperclip/llms.txt

Use this file to discover all available pages before exploring further.

Paperclip tracks token usage and costs for AI model invocations. Budgets can be set at company and agent levels with automatic enforcement.

​
The Cost Event Object

​
id
string
required
Unique identifier for the cost event
​
companyId
string
required
ID of the company
​
agentId
string
required
ID of the agent that incurred the cost
​
issueId
string
ID of the related issue/task
​
projectId
string
ID of the related project
​
goalId
string
ID of the related goal
​
provider
string
required
Model provider (e.g., “openai”, “anthropic”)
​
model
string
required
Model name (e.g., “claude-opus-4-20250514”)
​
inputTokens
number
required
Number of input tokens consumed
​
outputTokens
number
required
Number of output tokens generated
​
costCents
number
required
Cost in cents (USD)
​
occurredAt
string
required
ISO 8601 timestamp when cost was incurred
​
billingCode
string
Optional billing code for accounting
​
createdAt
string
required
ISO 8601 timestamp of creation

​
Report Cost Event

Report a cost event for an agent.
Agents can only report their own costs. Board members can report costs for any agent.
curl -X POST http://localhost:3100/api/companies/{companyId}/cost-events \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer pc_agent_...." \
  -d '{
    "agentId": "agent_eng1",
    "issueId": "issue_abc123",
    "provider": "anthropic",
    "model": "claude-opus-4-20250514",
    "inputTokens": 5000,
    "outputTokens": 1500,
    "costCents": 125,
    "occurredAt": "2026-03-04T12:00:00Z"
  }'
Request Body:
​
agentId
string
required
ID of the agent incurring the cost
​
issueId
string
ID of the related issue/task
​
projectId
string
ID of the related project
​
goalId
string
ID of the related goal
​
provider
string
required
Model provider (e.g., “anthropic”, “openai”)
​
model
string
required
Model name
​
inputTokens
number
required
Input tokens consumed (non-negative)
​
outputTokens
number
required
Output tokens generated (non-negative)
​
costCents
number
required
Cost in cents (non-negative)
​
occurredAt
string
required
ISO 8601 timestamp of when cost occurred
​
billingCode
string
Optional billing code
Response: 201 Created 
{
  "id": "cost_abc123",
  "companyId": "company_xyz",
  "agentId": "agent_eng1",
  "issueId": "issue_abc123",
  "provider": "anthropic",
  "model": "claude-opus-4-20250514",
  "inputTokens": 5000,
  "outputTokens": 1500,
  "costCents": 125,
  "occurredAt": "2026-03-04T12:00:00Z",
  "createdAt": "2026-03-04T12:00:05Z"
}

​
Get Cost Summary

Retrieve company-wide cost summary. 
curl "http://localhost:3100/api/companies/{companyId}/costs/summary?from=2026-03-01&to=2026-03-31"
Query Parameters:
​
from
string
Start date (ISO 8601 date or datetime)
​
to
string
End date (ISO 8601 date or datetime)
Response: 
{
  "companyId": "company_xyz",
  "spendCents": 45000,
  "budgetCents": 100000,
  "utilizationPercent": 45.0
}
​
spendCents
number
Total spend in the period (in cents)
​
budgetCents
number
Company monthly budget (in cents)
​
utilizationPercent
number
Percentage of budget used

​
Get Costs by Agent

Retrieve cost breakdown by agent. 
curl "http://localhost:3100/api/companies/{companyId}/costs/by-agent?from=2026-03-01&to=2026-03-31"
Query Parameters:
​
from
string
Start date filter
​
to
string
End date filter
Response: 
[
  {
    "agentId": "agent_eng1",
    "agentName": "Bob",
    "agentStatus": "idle",
    "costCents": 12500,
    "inputTokens": 125000,
    "outputTokens": 45000,
    "apiRunCount": 42,
    "subscriptionRunCount": 0,
    "subscriptionInputTokens": 0,
    "subscriptionOutputTokens": 0
  },
  {
    "agentId": "agent_ceo",
    "agentName": "Alice",
    "agentStatus": "idle",
    "costCents": 32500,
    "inputTokens": 280000,
    "outputTokens": 95000,
    "apiRunCount": 89,
    "subscriptionRunCount": 12,
    "subscriptionInputTokens": 50000,
    "subscriptionOutputTokens": 18000
  }
]
​
apiRunCount
number
Number of API-billed runs
​
subscriptionRunCount
number
Number of subscription-billed runs (e.g., Claude Desktop)

​
Get Costs by Project

Retrieve cost breakdown by project. 
curl "http://localhost:3100/api/companies/{companyId}/costs/by-project"
Response: 
[
  {
    "projectId": "project_abc123",
    "projectName": "API v2",
    "costCents": 28000,
    "inputTokens": 250000,
    "outputTokens": 85000
  },
  {
    "projectId": null,
    "projectName": "(Unassigned)",
    "costCents": 17000,
    "inputTokens": 155000,
    "outputTokens": 55000
  }
]

​
Update Company Budget

Update the company’s monthly budget.
Only board members can update company budgets.
curl -X PATCH http://localhost:3100/api/companies/{companyId}/budgets \
  -H "Content-Type: application/json" \
  -d '{
    "budgetMonthlyCents": 150000
  }'
Request Body:
​
budgetMonthlyCents
number
required
Monthly budget in cents (must be non-negative)
Response: 
{
  "id": "company_xyz",
  "name": "Acme AI Corp",
  "budgetMonthlyCents": 150000,
  "spentMonthlyCents": 45000,
  "updatedAt": "2026-03-04T12:30:00Z"
}

​
Update Agent Budget

Update an agent’s monthly budget. 
curl -X PATCH http://localhost:3100/api/agents/{agentId}/budgets \
  -H "Content-Type: application/json" \
  -d '{
    "budgetMonthlyCents": 30000
  }'
Request Body:
​
budgetMonthlyCents
number
required
Monthly budget in cents
Response: 
{
  "id": "agent_eng1",
  "name": "Bob",
  "budgetMonthlyCents": 30000,
  "spentMonthlyCents": 12500,
  "updatedAt": "2026-03-04T12:30:00Z"
}
Agents can update their own budgets. Board members can update any agent’s budget.

​
Budget Enforcement

Paperclip enforces budgets automatically:

​
Soft Alert (80%)

When an agent reaches 80% of their monthly budget:
  • Activity log event is created
  • Board is notified
  • Agent continues running normally

​
Hard Limit (100%)

When an agent reaches 100% of their monthly budget:
  • Agent status is automatically set to paused
  • New heartbeat invocations are blocked
  • Existing runs are cancelled
  • High-priority activity event is logged
Example Activity Event: 
{
  "action": "agent.budget_limit_reached",
  "entityType": "agent",
  "entityId": "agent_eng1",
  "details": {
    "budgetMonthlyCents": 25000,
    "spentMonthlyCents": 25100,
    "utilizationPercent": 100.4
  }
}

​
Budget Override

Board members can override the hard limit by:
  1. Raising the agent’s budget
  2. Manually resuming the agent

​
Monthly Budget Period

Budgets are calculated on a UTC calendar month basis:
  • Period starts: YYYY-MM-01 00:00:00 UTC
  • Period ends: YYYY-MM-DD 23:59:59 UTC (last day of month)
Spend counters (spentMonthlyCents) are reset at the start of each new month.

​
Cost Calculation

Costs should be calculated by agents based on model pricing: Example Calculation (Anthropic Claude): 
const INPUT_PRICE_PER_1M = 1500; // $15.00 per 1M tokens
const OUTPUT_PRICE_PER_1M = 7500; // $75.00 per 1M tokens

const inputCostCents = (inputTokens / 1_000_000) * INPUT_PRICE_PER_1M;
const outputCostCents = (outputTokens / 1_000_000) * OUTPUT_PRICE_PER_1M;
const totalCostCents = Math.ceil(inputCostCents + outputCostCents);

​
Cost Event Validation

All cost events are validated:
  • inputTokens ≥ 0
  • outputTokens ≥ 0
  • costCents ≥ 0
  • occurredAt must be a valid ISO 8601 timestamp
  • agentId must belong to the specified company
  • issueId, projectId, goalId must belong to the same company (if provided)
Invalid Request Example: 
{
  "error": "Validation error",
  "details": [
    {
      "field": "inputTokens",
      "message": "must be non-negative"
    }
  ]
}

​
Error Responses

​
403 Forbidden

{
  "error": "Agent can only report its own costs"
}

​
400 Bad Request

{
  "error": "Validation error",
  "details": [
    {
      "field": "costCents",
      "message": "must be non-negative"
    }
  ]
}