Overview The Usage API provides information about your API key usage, rate limits, and authentication details. This endpoint is useful for monitoring your API consumption and ensuring you stay within rate limits.
Authentication Requires read or read_write scope.
Endpoint Retrieve usage information for your current authentication method.
Response The response varies depending on your authentication method (API Key or OAuth).
{ "api_key" : { "name" : "Production API Key" , "scopes" : [ "read" , "read_write" ], "last_used_at" : "2024-03-04T16:30:00Z" , "created_at" : "2024-01-01T00:00:00Z" }, "rate_limit" : { "tier" : "standard" , "limit" : 1000 , "current_count" : 245 , "remaining" : 755 , "reset_in_seconds" : 2847 , "reset_at" : "2024-03-04T17:30:00Z" } }
{ "authentication_method" : "oauth" , "message" : "Detailed usage tracking is available for API key authentication" }
Example Request curl -X GET https://your-domain.com/api/v1/usage \ -H "X-Api-Key: your_api_key_here"
Response Fields API Key Response Human-readable name of the API key
Array of permission scopes granted to this API key (e.g., ["read", "read_write"])
ISO 8601 timestamp of the last time this API key was used
ISO 8601 timestamp when the API key was created
Rate limit tier for this API key (e.g., standard, premium)
Maximum number of requests allowed per time window
Number of requests made in the current time window
Number of requests remaining in the current time window
Seconds until the rate limit counter resets
ISO 8601 timestamp when the rate limit will reset
OAuth Response Authentication method used (oauth)
Information about usage tracking availability
In addition to the usage endpoint, rate limit information is included in response headers for every API request when using API key authentication:
X-RateLimit-Limit : 1000 X-RateLimit-Remaining : 755 X-RateLimit-Reset : 2847
Maximum requests allowed per window
Requests remaining in current window
Seconds until limit resets
Rate Limit Exceeded When you exceed your rate limit, the API returns a 429 Too Many Requests response:
{ "error" : "rate_limit_exceeded" , "message" : "Rate limit exceeded. Try again in 2847 seconds." , "details" : { "limit" : 1000 , "current" : 1001 , "reset_in_seconds" : 2847 } }
Additional headers are included:
X-RateLimit-Limit : 1000 X-RateLimit-Remaining : 0 X-RateLimit-Reset : 2847 Retry-After : 2847
Error Responses { "error" : "invalid_authentication_method" , "message" : "Unable to determine usage information" }
{ "error" : "unauthorized" , "message" : "Access token or API key is invalid, expired, or missing" }
{ "error" : "insufficient_scope" , "message" : "This action requires the 'read' scope" }
Rate Limit Tiers Rate limits are applied per API key and typically follow these tiers:
Standard Tier : Default rate limit for most API keysPremium Tier : Higher limits for production applications (contact your administrator)Custom Tier : Custom limits for enterprise deployments
Best Practices Monitor Your Usage Regularly check your usage to avoid hitting rate limits:
# Check current usage before making bulk requests curl -X GET https://your-domain.com/api/v1/usage \ -H "X-Api-Key: your_api_key_here"
Always read the rate limit headers in responses:
import requests response = requests.get( 'https://your-domain.com/api/v1/transactions' , headers = { 'X-Api-Key' : 'your_api_key' } ) remaining = int (response.headers.get( 'X-RateLimit-Remaining' , 0 )) if remaining < 10 : print ( f "Warning: Only { remaining } requests remaining" )
Handle Rate Limit Errors Implement exponential backoff when you hit rate limits:
import time import requests def make_request_with_retry ( url , headers , max_retries = 3 ): for attempt in range (max_retries): response = requests.get(url, headers = headers) if response.status_code == 429 : retry_after = int (response.headers.get( 'Retry-After' , 60 )) print ( f "Rate limited. Retrying in { retry_after } seconds..." ) time.sleep(retry_after) continue return response raise Exception ( "Max retries exceeded" )
Use Multiple API Keys For high-volume applications, consider using multiple API keys to distribute load:
Each API key has its own rate limit counter. Make sure each key has appropriate scopes and is properly secured.
OAuth vs API Key Usage API Key Authentication : Full usage tracking with rate limits per key. Ideal for server-to-server integrations.OAuth Authentication : Currently has limited usage tracking. Best for user-authorized applications and mobile apps.
Notes
Rate limits reset on a rolling window basis (typically hourly)
The last_used_at timestamp updates with each API request
Deactivated API keys will not authenticate, even if they have remaining quota
Usage tracking helps you optimize your API integration and avoid service interruptions