Usage Metrics & Quotas
Relevant source files
The following files were used as context for generating this wiki page:
The Usage Metrics & Quotas system provides comprehensive visibility into account-level consumption and API limitations. It tracks resource utilization across emails, contacts, domains, and AI credits, while enforcing rate limits to ensure service stability.
This system consists of two primary mechanisms: the Usage module for account-wide status and the Emails.metrics endpoint for granular deliverability data. It exposes usage data through structured Python TypedDict objects and standard HTTP response headers for real-time rate limit tracking.
Account-Level Usage
The Usage class retrieves account-level consumption data. It provides both synchronous and asynchronous methods to fetch a snapshot of current utilization against defined limits.
Usage Architecture
The Usage.get() method sends a GET request to the /usage endpoint. The SDK parses the JSON response into a GetResponse object containing specific usage dictionaries for different resource types.
Resource Quotas
The SDK tracks usage for multiple resource types. Each resource typically includes a used count and a limit. Some resources also include reset timestamps or increase schedules.
| Resource | Field | Type | Description |
|---|---|---|---|
| Emails | daily | EmailsDailyUsage | Tracks used, limit, sent, and received count for the current day. |
monthly | EmailsMonthlyUsage | Tracks used, limit, sent, and received count for the current month. | |
| Contacts | used/limit | int | Number of contacts against the account quota. |
| Domains | used/limit | int | Number of verified domains against the account quota. |
| AI Credits | used/limit | int | AI credit consumption; includes next_increase_at. |
| Automations | used/limit | int | Number of automation runs; includes resets_at. |
Sources: resend/usage/_usage.py:15-156, tests/usage_test.py:13-43
Email Performance Metrics
The Emails.metrics method retrieves detailed deliverability and engagement statistics. Unlike general account usage, these metrics focus on the performance of sent communications over specific time ranges.
Metrics Dimensions and Filters
You can break down metrics by dimensions such as domain, email, or period. You can also filter results by specific IDs.
Sources: resend/emails/_emails.py:144-245
Available Performance Metrics
The system computes various metrics including:
- Delivery:
sent,delivered,delivery_delayed,delivery_rate. - Engagement:
opened,clicked,unique_opened,open_rate,click_rate. - Failures:
bounced,bounced_permanent,complained,bounce_rate. - Retention:
unsubscribed,unsubscribe_rate.
Sources: resend/emails/_emails.py:31-53
Rate Limiting
Rate limits control the frequency of API requests. The SDK provides two ways to monitor these limits: via the Usage object and through HTTP response headers.
Rate Limit Configuration
The Usage response includes a RateLimitUsage dictionary that defines the allowed threshold.
- limit: The number of requests allowed per duration window.
- duration: The window size (e.g., "1000ms").
Sources: resend/usage/_usage.py:159-166, tests/usage_test.py:43-44
Real-time Tracking via Headers
Every successful API request returns HTTP headers that indicate the current rate limit status. The SDK injects these into the http_headers field of response objects.
resp = resend.Emails.send(params)
# Accessing rate limit metadata from headers
if "http_headers" in resp:
limit = resp["http_headers"].get("ratelimit-limit")
remaining = resp["http_headers"].get("ratelimit-remaining")
reset = resp["http_headers"].get("ratelimit-reset")
Sources: examples/with_headers.py:44-50, resend/request.py:152-154
Data Flow for Usage Retrieval
The following sequence diagram illustrates the internal SDK flow when a developer requests account usage data.
Summary
The Usage Metrics & Quotas system enables precise monitoring of account health and resource consumption. By providing both high-level account snapshots via the Usage module and granular deliverability insights through Emails.metrics, the SDK allows developers to stay within quotas and optimize email performance. Real-time rate limit tracking via http_headers ensures applications can dynamically adjust request frequency to prevent 429 (Too Many Requests) errors.