Get Usage

GET/v1/usageBETA+ Required

Retrieve comprehensive usage statistics for your account, including token consumption, request counts, per-model breakdowns, per-endpoint breakdowns, and estimated costs.

Warning

Tier Requirement: This endpoint is only available for BETA and PRO tier users. FREE tier users will receive a 403 Forbidden error. Upgrade your plan to access detailed usage metrics.

Information

Data Retention: Detailed request logs are retained for 24 hours only. Aggregated usage metrics are preserved indefinitely. Cost calculations are estimates based on token usage.

Authentication

This endpoint requires JWT authentication via the Authorization header:

JWT Token: Include your Better Auth JWT token in the Authorization header
Tier Access: Your account must be BETA or PRO tier

Request

Headers

Authorization: Bearer YOUR_JWT_TOKEN

Query Parameters (Optional)

You can filter usage data by time range:

Parameter	Type	Default	Description
range	string	24h	Time range: `24h`, `7d`, or `30d`. Note: Only last 24 hours have detailed logs.

Response

Success Response (200 OK)

Returns detailed usage statistics for the provided API key.

Response Fields

Field	Type	Description
total_requests	integer	Total number of API requests in the time range
input_tokens	integer	Total input tokens consumed
output_tokens	integer	Total output tokens generated
cost	float	Estimated total cost based on token usage
by_model	object	Per-model usage breakdown (see below)
by_endpoint	object	Per-endpoint usage breakdown (see below)

By Model Object

The by_model field contains a breakdown of usage per model. Each model key contains:

Field	Type	Description
total_requests	integer	Total requests for this model
input_tokens	integer	Input tokens for this model
output_tokens	integer	Output tokens for this model
cost	float	Estimated cost for this model

By Endpoint Object

The by_endpoint field contains a breakdown of usage per API endpoint. Each endpoint key contains:

Field	Type	Description
total_requests	integer	Total requests to this endpoint
input_tokens	integer	Input tokens for this endpoint
output_tokens	integer	Output tokens for this endpoint

Example Response

1{
2  "total_requests": 150,
3  "input_tokens": 45000,
4  "output_tokens": 28000,
5  "cost": 0.0234,
6  "by_model": {
7    "Selam-Plus": {
8      "total_requests": 80,
9      "input_tokens": 25000,
10      "output_tokens": 18000,
11      "cost": 0.0156
12    },
13    "Selam-Lite": {
14      "total_requests": 70,
15      "input_tokens": 20000,
16      "output_tokens": 10000,
17      "cost": 0.0078
18    }
19  },
20  "by_endpoint": {
21    "/v1/chat/completions": {
22      "total_requests": 120,
23      "input_tokens": 38000,
24      "output_tokens": 25000
25    },
26    "/v1/completions": {
27      "total_requests": 30,
28      "input_tokens": 7000,
29      "output_tokens": 3000
30    }
31  }
32}

Error Responses

401 Unauthorized

Invalid or missing JWT token.

{
  "error": "Unauthorized: invalid or missing token"
}

403 Forbidden

FREE tier users attempting to access this endpoint.

{
  "error": "Usage endpoint is only available for BETA and PRO tier users",
  "current_tier": "FREE",
  "required_tier": "BETA+",
  "message": "Upgrade to BETA tier or higher to access detailed usage metrics"
}

404 Not Found

User not found in the database.

{
  "error": "User not found"
}

Examples

1import requests
2
3url = "https://api.selamgpt.com/v1/usage?range=24h"
4headers = {
5    "Authorization": "Bearer YOUR_JWT_TOKEN"
6}
7
8response = requests.get(url, headers=headers)
9usage_data = response.json()
10
11print(f"Total requests: {usage_data['total_requests']}")
12print(f"Input tokens: {usage_data['input_tokens']:,}")
13print(f"Output tokens: {usage_data['output_tokens']:,}")
14print(f"Total cost: ${usage_data['cost']:.4f}")
15
16# Print per-model breakdown
17print("\nUsage by Model:")
18for model, stats in usage_data['by_model'].items():
19    print(f"  {model}:")
20    print(f"    Requests: {stats['total_requests']}")
21    print(f"    Tokens: {stats['input_tokens']:,} in, {stats['output_tokens']:,} out")
22    print(f"    Cost: ${stats['cost']:.4f}")
23
24# Print per-endpoint breakdown
25print("\nUsage by Endpoint:")
26for endpoint, stats in usage_data['by_endpoint'].items():
27    print(f"  {endpoint}: {stats['total_requests']} requests")

Use Cases

Monitor API Usage

Track your API consumption to understand usage patterns and optimize costs. The per-model and per-endpoint breakdowns help identify which models and endpoints are most used.

Budget Management

Monitor total costs and set up alerts when approaching budget limits. The cost field provides real-time estimated cost tracking based on token usage.

Performance Analysis

Analyze token consumption patterns to optimize your prompts and model selection. Compare usage across different models to find the best balance of cost and performance.

Capacity Planning

Analyze token consumption trends to plan for scaling and tier upgrades. The token counts help predict future usage and costs.

Tip

Pro Tip: Set up automated monitoring by calling this endpoint periodically and tracking metrics over time. This helps identify usage spikes and optimize your API integration. Remember that detailed logs are only retained for 24 hours, so query frequently if you need granular historical data.

Information

Data Retention: Detailed request logs (used for the by_model andby_endpoint breakdowns) are retained for 24 hours only. If you query withrange=7d or range=30d, you'll only see data from the last 24 hours. For long-term analytics, export and store usage data externally.

Was this page helpful?

List Languages

Get supported languages