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

# Quotas

> Understand daily quotas and how to manage them

## Overview

OathNet uses **daily quotas** to manage API usage. Each plan has a set number of lookups available per day.

## Quota Reset

Your daily quota resets **24 hours after your first lookup of the day**. This is a rolling window, not a fixed time.

For example:

* If your first lookup is at 2:00 PM, your quota resets the next day at 2:00 PM
* The exact reset time is shown in the response metadata

## Checking Your Quota

Envelope search responses expose lookup usage in `_meta.lookups`:

```json theme={null}
{
  "success": true,
  "data": { "...": "..." },
  "_meta": {
    "lookups": {
      "used_today": 50,
      "left_today": 450,
      "daily_limit": 500,
      "is_unlimited": false
    }
  }
}
```

<Note>
  Not every successful endpoint includes quota metadata. Search endpoints do; raw job endpoints and file-stream endpoints may not.
</Note>

## Optimizing Quota Usage

### Use Search Sessions

Search sessions let you perform multiple searches for the same query while only consuming **one lookup**:

```python theme={null}
# Initialize session (counts as 1 lookup)
session = requests.post(
    "https://oathnet.org/api/service/search/init",
    json={"query": "user@example.com"},
    headers={"x-api-key": API_KEY}
).json()

session_id = session["data"]["session"]["id"]

# Additional searches with same session don't consume quota
for page in range(10):
    response = requests.get(
        "https://oathnet.org/api/service/v2/breach/search",
        params={"q": "user@example.com", "search_id": session_id},
        headers={"x-api-key": API_KEY}
    )
```

See [Search Sessions](/guides/search-sessions) for more details.

### Failed Requests Don't Count

Failed requests (4xx/5xx errors) do **not** count against your quota. You're only charged for successful lookups.

## Plan Quotas

Each plan has different quota limits. View current plans and quotas at:

<Card title="View Pricing" icon="tag" href="https://oathnet.org/pricing">
  See quota limits for each plan
</Card>

## Handling Quota Exhaustion

When your quota is exhausted, you'll receive a 429 response:

```json theme={null}
{
  "success": false,
  "message": "Daily quota exceeded"
}
```

Options when this happens:

* Wait for your quota to reset (24 hours from first lookup)
* Upgrade your plan for more lookups

## Best Practices

<AccordionGroup>
  <Accordion title="Monitor Your Usage" icon="gauge">
    Track `_meta.lookups.left_today` on envelope search responses to avoid unexpected quota exhaustion:

    ```python theme={null}
    response = api_call(query)
    lookups = response.get("_meta", {}).get("lookups", {})
    lookups_left = lookups.get("left_today")

    if lookups_left is not None and lookups_left < 100:
        print(f"Warning: Only {lookups_left} lookups remaining")
    ```
  </Accordion>

  <Accordion title="Use Search Sessions" icon="clock">
    For repeated searches on the same query, always use search sessions to minimize quota usage.
  </Accordion>

  <Accordion title="Cache Results" icon="database">
    Cache API responses locally to avoid redundant lookups:

    ```python theme={null}
    from functools import lru_cache

    @lru_cache(maxsize=1000)
    def cached_search(query):
        return api_call(query)
    ```
  </Accordion>
</AccordionGroup>

## Questions?

Contact [support@oathnet.org](mailto:support@oathnet.org) if you have questions about quotas or need a custom plan.