Expenses API

Create an Expense

POST /v1/expenses

Creates a new expense. For LLM cost tracking, use the “LLM Usage” expense category.

Request Body

Field	Type	Required	Description
`project_id`	string	Yes	Project ID
`expense_category_id`	string	Yes	Expense category ID
`spent_date`	string	Yes	Date of expense (YYYY-MM-DD)
`total_cost`	number	Yes*	Total cost amount
`units`	number	No	Quantity (e.g., tokens in thousands)
`unit_price`	number	No	Price per unit
`notes`	string	No	Description
`source`	string	No	`web`, `cli`, `api`, `agent`
`metadata`	object	No	Agent context JSON (max 4KB)

*If units and unit_price are provided, total_cost is calculated automatically.

Example: Log LLM Token Cost

curl -X POST https://api.keito.ai/v1/expenses \
  -H "Authorization: Bearer keito_sk_abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "project_id": "prj_abc",
    "expense_category_id": "cat_llm_usage",
    "spent_date": "2026-03-06",
    "units": 45,
    "notes": "claude-opus-4-6: 30k input + 15k output tokens",
    "source": "agent",
    "metadata": {
      "agent_id": "review-bot-01",
      "session_id": "550e8400-e29b-41d4-a716-446655440000",
      "model": "claude-opus-4-6",
      "input_tokens": 30000,
      "output_tokens": 15000
    }
  }'

Example Response

{
  "id": "exp_xyz789",
  "project_id": "prj_abc",
  "expense_category_id": "cat_llm_usage",
  "spent_date": "2026-03-06",
  "units": 45,
  "unit_price": 0.003,
  "total_cost": 0.135,
  "notes": "claude-opus-4-6: 30k input + 15k output tokens",
  "source": "agent",
  "metadata": {
    "agent_id": "review-bot-01",
    "session_id": "550e8400-e29b-41d4-a716-446655440000",
    "model": "claude-opus-4-6",
    "input_tokens": 30000,
    "output_tokens": 15000
  },
  "created_at": "2026-03-06T14:35:00Z"
}

List Expenses

GET /v1/expenses

Returns a paginated list of expenses. Supports the same source, project, user, and date filters as time entries.

Example: List All LLM Expenses for a Project

curl "https://api.keito.ai/v1/expenses?source=agent&project_id=prj_abc&from=2026-03-01" \
  -H "Authorization: Bearer keito_sk_abc123"