REST API Examples
cURL ReadyUse Bear Lumen REST API directly with cURL, Postman, or any HTTP client. No SDK required. All examples use standard HTTP requests that work in any programming language.
Authentication
All API requests require an SDK API key passed via the Authorization: Bearer sk_test_... header. API keys are scoped with specific permissions (e.g., usage:write, costs:read).
bash
# Get your API key from the Bear Lumen dashboard
# API keys start with sk_ and require specific scopes
curl https://api.bearlumen.com/v1/ping \
-H "Authorization: Bearer sk_test_YOUR_API_KEY"
Security: Never commit API keys to version control. Use environment variables in production.
Usage Tracking
Record AI usage events to track costs. Each event captures the model, provider, and token count. Requires usage:write scope.
POST
Record Usage Event
bash
curl -X POST https://api.bearlumen.com/v1/usage/events \
-H "Authorization: Bearer sk_test_YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"eventType": "llm_call",
"metricName": "tokens",
"quantity": 1500,
"idempotencyKey": "evt_unique_key_123",
"metadata": {
"model": "gpt-4o",
"provider": "openai",
"feature": "chat"
}
}'
View Response
JSON
{
"eventId": "evt_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"userId": "user_abc123",
"metricName": "tokens",
"quantity": 1500,
"eventTimestamp": "2026-01-13T10:35:00.000Z",
"recorded": true
}
POST
Record Batch Usage Events (up to 1000)
bash
curl -X POST https://api.bearlumen.com/v1/usage/events/batch \
-H "Authorization: Bearer sk_test_YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"events": [
{
"eventType": "llm_call",
"metricName": "tokens",
"quantity": 1200,
"idempotencyKey": "evt_batch_001",
"metadata": { "model": "claude-3-sonnet", "provider": "anthropic" }
},
{
"eventType": "llm_call",
"metricName": "tokens",
"quantity": 800,
"idempotencyKey": "evt_batch_002",
"metadata": { "model": "gpt-4o-mini", "provider": "openai" }
}
]
}'
Idempotency: Always include an idempotencyKey to prevent duplicate usage recording if requests are retried.
Cost Data
Query aggregated cost data across your organization. Requires costs:read scope.
GET
Get Cost Summary
bash
curl "https://api.bearlumen.com/v1/cost-data/summary?time_window=current-period" \
-H "Authorization: Bearer sk_test_YOUR_API_KEY"
View Response
JSON
{
"totalCost": 1234.56,
"previousPeriodCost": 1100.00,
"changeAmount": 134.56,
"changePercent": 12.23,
"periodStart": "2026-01-01T00:00:00.000Z",
"periodEnd": "2026-01-31T23:59:59.999Z"
}
GET
Cost Breakdown by Model
bash
curl "https://api.bearlumen.com/v1/cost-data/by-model?start_date=2026-01-01&end_date=2026-01-31" \
-H "Authorization: Bearer sk_test_YOUR_API_KEY"
View Response
JSON
{
"breakdown": [
{ "model": "gpt-4o", "totalCost": 580.25, "eventCount": 12500, "percentOfTotal": 47.0 },
{ "model": "claude-3-sonnet", "totalCost": 350.10, "eventCount": 8200, "percentOfTotal": 28.4 },
{ "model": "gpt-4o-mini", "totalCost": 304.21, "eventCount": 45000, "percentOfTotal": 24.6 }
]
}
GET
Cost Breakdown by Provider
bash
curl "https://api.bearlumen.com/v1/cost-data/by-provider?start_date=2026-01-01&end_date=2026-01-31" \
-H "Authorization: Bearer sk_test_YOUR_API_KEY"
GET
Cost Trend (Time Series)
bash
curl "https://api.bearlumen.com/v1/cost-data/trend?start_date=2026-01-01&end_date=2026-01-31" \
-H "Authorization: Bearer sk_test_YOUR_API_KEY"
End User Costs
Query costs scoped to a specific end user by their external ID (the userId set in SDK track options). Requires costs:read scope.
GET
End User Cost Summary
bash
curl "https://api.bearlumen.com/v1/end-user-costs/user_123/summary?start_date=2026-01-01&end_date=2026-01-31" \
-H "Authorization: Bearer sk_test_YOUR_API_KEY"
View Response
JSON
{
"endUserId": "euid_abc123",
"externalId": "user_123",
"totalCost": 245.80,
"previousPeriodCost": 210.50,
"changeAmount": 35.30,
"changePercent": 16.77,
"periodStart": "2026-01-01T00:00:00.000Z",
"periodEnd": "2026-01-31T00:00:00.000Z"
}
GET
End User Cost by Model
bash
curl "https://api.bearlumen.com/v1/end-user-costs/user_123/by-model?start_date=2026-01-01&end_date=2026-01-31" \
-H "Authorization: Bearer sk_test_YOUR_API_KEY"
Error Handling
All error responses include a human-readable correlation ID for support reference.
| Code | Description |
|---|---|
| 200 | OK - Request succeeded |
| 201 | Created - Usage event recorded successfully |
| 400 | Bad Request - Invalid parameters or request body |
| 401 | Unauthorized - Missing or invalid API key |
| 403 | Forbidden - API key lacks required scope |
| 404 | Not Found - End user or resource doesn't exist |
| 429 | Too Many Requests - Rate limit exceeded |
| 500 | Server Error - Something went wrong on our end |
Error Response Format
JSON
{
"success": false,
"error": {
"code": "VALIDATION_ERROR",
"message": "Invalid time_window: weekly. Valid options: current-period, last-period, last-7-days, last-30-days",
"correlationId": "OLIVE-DINOSAUR-1b2fE4",
"details": {
"retryable": false
}
},
"meta": {
"timestamp": "2026-01-13T10:35:00.000Z",
"path": "/v1/cost-data/summary",
"method": "GET"
}
}