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

# Query Usage & Limits

> Track query usage against your plan quota and handle rate limits

Memvid tracks query usage against your plan's monthly quota. Every `find` and `ask` operation counts toward your limit, regardless of whether you use the CLI, Python SDK, or Node.js SDK.

***

## How Query Tracking Works

1. Each `find` or `ask` operation counts as **1 query**
2. Usage is tracked per **API key**
3. Quota resets on your **monthly billing date**
4. Tracking happens server-side (requires API key)

```mermaid theme={null}
flowchart LR
    A[CLI/SDK<br/>find/ask] --> B[Dashboard API]
    B --> C[Quota Check]
    C --> D{Allow or Reject}
```

***

## Plan Limits

| Plan       | Monthly Queries | Storage |
| ---------- | --------------- | ------- |
| Free       | Unlimited       | 50 MB   |
| Starter    | 50,000          | 25 GB   |
| Pro        | 250,000         | 125 GB  |
| Enterprise | Unlimited       | Custom  |

<Note>
  Queries are counted even for local `.mv2` files when an API key is configured. This enables usage tracking across all your memories.
</Note>

***

## Checking Your Usage

### CLI

```bash theme={null}
# Show current plan and usage
memvid plan show
```

Output:

```
Plan: starter
Status: active

Usage (this period):
  Queries: 12,847 / 50,000 (25.7%)
  Storage: 10.5 GB / 25 GB (42.0%)

Billing period:
  Started: 2024-12-01
  Resets: 2025-01-01 (in 15 days)

Dashboard: https://memvid.com/dashboard/plan
```

JSON output for scripting:

```bash theme={null}
memvid plan show --json
```

```json theme={null}
{
  "plan": "starter",
  "status": "active",
  "queries": {
    "used": 12847,
    "limit": 25000,
    "remaining": 12153,
    "percent": 51.39
  },
  "storage": {
    "used_bytes": 2254857830,
    "limit_bytes": 5368709120,
    "percent": 42.0
  },
  "period": {
    "start": "2024-12-01T00:00:00Z",
    "end": "2025-01-01T00:00:00Z",
    "days_remaining": 15
  }
}
```

### Dashboard

Visit [memvid.com/dashboard/plan](https://memvid.com/dashboard/plan) to see:

* Real-time usage graphs
* Historical usage trends
* Billing information
* Upgrade options

***

## Quota Exceeded Error

When you exceed your monthly quota, queries will fail with error **MV023**:

```bash theme={null}
memvid find memory.mv2 --query "search term"
```

```
Error: Monthly query quota exceeded (MV023)

Used: 25,000 / 25,000
Resets: 2025-01-01 (in 3 days)

Options:
  1. Wait for quota reset
  2. Upgrade plan: https://memvid.com/dashboard/plan
```

***

## SDK Error Handling

### Python

```python theme={null}
from memvid import use, QuotaExceededError, MemvidError

mem = use('basic', 'memory.mv2')

try:
    results = mem.find("search query")
except QuotaExceededError as e:
    print(f"Quota exceeded!")
    print(f"Used: {e.used} / {e.limit}")
    print(f"Resets: {e.reset_date}")
    print(f"Upgrade at: {e.upgrade_url}")
except MemvidError as e:
    print(f"Other error: {e}")
```

The `QuotaExceededError` includes:

* `used`: Queries used this period
* `limit`: Plan query limit
* `remaining`: Queries remaining (0 when exceeded)
* `reset_date`: When quota resets (ISO 8601)
* `upgrade_url`: Link to upgrade page

### Node.js

```typescript theme={null}
import { use, QuotaExceededError, MemvidError } from '@anthropics/memvid'

const mem = await use('basic', 'memory.mv2')

try {
  const results = await mem.find("search query")
} catch (e) {
  if (e instanceof QuotaExceededError) {
    console.log(`Quota exceeded!`)
    console.log(`Used: ${e.used} / ${e.limit}`)
    console.log(`Resets: ${e.resetDate}`)
    console.log(`Upgrade at: ${e.upgradeUrl}`)
  } else if (e instanceof MemvidError) {
    console.log(`Other error: ${e.message}`)
  }
}
```

***

## Rate Limiting

In addition to monthly quotas, there are per-minute rate limits to prevent abuse:

| Plan       | Requests/minute |
| ---------- | --------------- |
| Free       | 60              |
| Starter    | 300             |
| Pro        | 1,000           |
| Enterprise | Custom          |

Rate limit errors return **HTTP 429** with headers:

```
X-RateLimit-Limit: 300
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1704067260
```

### Handling Rate Limits

```python theme={null}
import time
from memvid import use, RateLimitError

mem = use('basic', 'memory.mv2')

def search_with_retry(query, max_retries=3):
    for attempt in range(max_retries):
        try:
            return mem.find(query)
        except RateLimitError as e:
            if attempt < max_retries - 1:
                wait_time = e.retry_after or (2 ** attempt)
                print(f"Rate limited. Waiting {wait_time}s...")
                time.sleep(wait_time)
            else:
                raise
```

***

## Optimizing Query Usage

### 1. Use Batch Operations

Instead of multiple individual queries, batch when possible:

```python theme={null}
# Inefficient: 10 queries
for term in search_terms:
    results = mem.find(term)

# Better: Build compound queries when logical
results = mem.find(" OR ".join(search_terms))
```

### 2. Cache Results

Cache search results for repeated queries:

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

@lru_cache(maxsize=100)
def cached_search(query):
    return mem.find(query)
```

### 3. Use Appropriate Top-K

Don't fetch more results than needed:

```bash theme={null}
# Fetching 100 results when you only need 5
memvid find memory.mv2 --query "term" --top-k 100  # Wasteful

# Better: Request what you need
memvid find memory.mv2 --query "term" --top-k 5
```

### 4. Filter Before Querying

Use scopes and filters to narrow searches:

```bash theme={null}
# Search entire memory
memvid find memory.mv2 --query "report"  # Broad

# Better: Scope to relevant documents
memvid find memory.mv2 --query "report" --scope "finance/" --start 2024-01-01
```

***

## Monitoring Usage Programmatically

### Check Before Querying

```python theme={null}
from memvid import get_usage

usage = get_usage()
if usage['queries']['remaining'] < 100:
    print(f"Warning: Only {usage['queries']['remaining']} queries left")
    print(f"Resets: {usage['period']['end']}")
```

### Track Usage in Applications

```python theme={null}
class QueryTracker:
    def __init__(self, mem, warning_threshold=0.8):
        self.mem = mem
        self.warning_threshold = warning_threshold

    def find(self, query, **kwargs):
        usage = get_usage()
        percent_used = usage['queries']['used'] / usage['queries']['limit']

        if percent_used >= self.warning_threshold:
            print(f"Warning: {percent_used*100:.1f}% of quota used")

        return self.mem.find(query, **kwargs)
```

***

## Without API Key

If no API key is configured:

* Query tracking is **skipped**
* No quota limits apply
* Usage isn't recorded

This is useful for:

* Local development
* Offline usage
* Testing

```bash theme={null}
# Unset API key to disable tracking
memvid config unset api_key

# Queries work but aren't tracked
memvid find memory.mv2 --query "test"
```

<Warning>
  Without an API key, you can't access dashboard features like usage history, team sharing, or paid plan capacity.
</Warning>

***

## Syncing Plan Status

If your plan was recently upgraded, sync to get new limits:

```bash theme={null}
# Refresh plan information
memvid plan sync

# Clear cached ticket and re-fetch
memvid plan clear
memvid plan sync
```

***

## Common Issues

### "Quota exceeded" but dashboard shows remaining

1. **Cache lag**: Wait 1-2 minutes for sync
2. **Wrong API key**: Verify key matches dashboard

   ```bash theme={null}
   memvid config check
   ```
3. **Multiple keys**: Each API key has separate quota

### Queries not being tracked

1. **No API key**: Set one:

   ```bash theme={null}
   memvid config set api_key mv2_xxx
   ```
2. **Network issues**: Check connectivity to memvid.com
3. **Tracking is best-effort**: Network failures don't block queries

### Rate limited but under quota

Rate limits are per-minute, quotas are per-month:

* You can hit rate limits while having quota remaining
* Wait a minute or implement exponential backoff

***

## Enterprise Options

For high-volume usage:

* **Custom quotas**: Tailored to your needs
* **Dedicated infrastructure**: No shared rate limits
* **Priority support**: Direct engineering access
* **SLA guarantees**: Uptime commitments

Contact [enterprise@memvid.com](mailto:enterprise@memvid.com) for details.

***

## Next Steps

<CardGroup cols={2}>
  <Card title="Capacity & Plans" icon="gauge" href="/concepts/capacity-and-plans">
    Storage limits and plan features
  </Card>

  <Card title="CLI Configuration" icon="gear" href="/cli/advanced-commands">
    Set up API keys and configuration
  </Card>
</CardGroup>