Usage API

Endpoints for tracking AI usage and checking limits.

Authentication

All endpoints require JWT authentication.

---

Get User Usage

GET /api/usage

Get current user's AI usage statistics.

Query Parameters

Parameter	Type	Description
startDate	string	ISO date
endDate	string	ISO date

Response

{
  "summary": {
    "totalTokens": 125000,
    "totalCost": 2.45,
    "actionsCount": 89
  },
  "byAction": {
    "CONTENT_GENERATION": { "count": 45, "tokens": 80000 },
    "QUICK_REFINE": { "count": 32, "tokens": 35000 },
    "CHAT_MESSAGE": { "count": 12, "tokens": 10000 }
  }
}

---

Get Company Usage

GET /api/usage/company

Get company-wide AI usage (admin only).

Response

{
  "totalSpendCents": 875,
  "userBreakdown": [
    {
      "userId": "user_123",
      "userName": "John Doe",
      "userEmail": "john@example.com",
      "websiteAnalysis": 5,
      "fieldAnalysis": 10,
      "oneShotRefinement": 25,
      "chatSessions": 2,
      "totalCostCents": 245
    }
  ]
}

---

Get Usage History

GET /api/usage/history

Get detailed usage log.

Query Parameters

Parameter	Type	Description
limit	number	Results per page
offset	number	Pagination offset

Response

[
  {
    "id": "log_123",
    "action": "CONTENT_GENERATION",
    "model": "gpt-4",
    "inputTokens": 500,
    "outputTokens": 1200,
    "cost": 0.05,
    "createdAt": "2025-01-01T10:00:00Z"
  }
]

---

Export Usage CSV

GET /api/usage/export

Export usage data as CSV.

Query Parameters

Parameter	Type	Description
startDate	string	ISO date
endDate	string	ISO date

Response

Returns CSV file download with headers:

Date,Action,Model,InputTokens,OutputTokens,Cost

---

Check Limits

GET /api/usage/limits

Check current usage against plan limits.

Response

{
  "aiPosts": {
    "used": 45,
    "limit": 200,
    "remaining": 155,
    "percentUsed": 22.5
  },
  "websiteAnalysis": {
    "used": 3,
    "limit": 10,
    "remaining": 7
  }
}