> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mailofly.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Retrieve Usage

> Retrieve aggregated sending metrics, plan allowances, and active resource counts (Beta).

Inspect current monthly quota usage, delivery rates, active contact counts, and configured domain counts.

> **Beta Endpoint**: The usage schema is in active beta and subject to additive enhancements.

### Query Parameters

<ParamField query="days" type="number" default="30">
  Aggregation period window in days (1 to 90).
</ParamField>

### Response

<ResponseField name="data" type="object">
  <ResponseField name="periodDays" type="number">Active aggregation window.</ResponseField>
  <ResponseField name="emailsSent" type="number">Total emails sent in period.</ResponseField>
  <ResponseField name="delivered" type="number">Total delivered / opened / clicked count.</ResponseField>
  <ResponseField name="bounced" type="number">Total bounced count.</ResponseField>
  <ResponseField name="activeContacts" type="number">Current contacts count.</ResponseField>
  <ResponseField name="domains" type="number">Active domains count.</ResponseField>

  <ResponseField name="limits" type="object">
    <ResponseField name="emailsPerMonth" type="number">Monthly email allowance.</ResponseField>
    <ResponseField name="domainsAllowed" type="number">Domain allowance.</ResponseField>
    <ResponseField name="rateLimitPerSecond" type="number">Maximum API requests / sec.</ResponseField>
  </ResponseField>
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X GET "https://api.mailofly.com/api/v1/usage?days=30" \
    -H "Authorization: Bearer mf_live_your_api_key"
  ```
</RequestExample>

<ResponseExample>
  ```json 200 OK theme={null}
  {
    "data": {
      "periodDays": 30,
      "emailsSent": 12850,
      "delivered": 12790,
      "bounced": 60,
      "activeContacts": 4500,
      "domains": 3,
      "limits": {
        "emailsPerMonth": 50000,
        "domainsAllowed": 10,
        "rateLimitPerSecond": 10
      }
    }
  }
  ```
</ResponseExample>


## Related topics

- [Usage & Rate Limits](/api/usage-limits.md)
- [MCP Tools Reference](/mcp-server/tools.md)
- [Retrieve Attachment](/api/emails/retrieve-attachment.md)
- [Retrieve Metrics](/api/emails/retrieve-metrics.md)
- [Retrieve Contact](/api/contacts/get-contact.md)