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

# Usage Tracking

> Monitor API usage, costs, and consumption patterns with detailed analytics

<Info>
  PromptGuard provides comprehensive usage tracking to help you monitor API consumption, control costs, and optimize your AI application performance.
</Info>

## Usage Metrics Overview

### Key Metrics Tracked

PromptGuard tracks detailed usage metrics across all your API calls:

#### Request Metrics

* **Total Requests**: Number of API calls made
* **Successful Requests**: Requests completed without errors
* **Failed Requests**: Requests that returned errors
* **Blocked Requests**: Requests stopped by security policies

#### Token Consumption

* **Input Tokens**: Tokens in your prompts and messages
* **Output Tokens**: Tokens in AI model responses
* **Total Tokens**: Combined input and output token usage

#### Cost Tracking

* **Total Costs**: Complete spending across all providers
* **Cost per Model**: Spending breakdown by AI model
* **Cost per Provider**: Spending split between OpenAI, Anthropic, etc.
* **Daily/Monthly Trends**: Cost patterns over time

#### Performance Metrics

* **Average Latency**: Mean response time for requests
* **P95/P99 Latency**: High-percentile response times
* **Throughput**: Requests per second/minute/hour
* **Error Rates**: Percentage of failed requests

## Dashboard Analytics

### Real-Time Usage Dashboard

Access comprehensive usage analytics at [app.promptguard.co](https://app.promptguard.co):

#### Main Dashboard View

* **Current Usage**: Real-time request and token consumption
* **Cost Tracking**: Today's spending and monthly projections
* **Performance Overview**: Latency and error rate summaries
* **Security Events**: Blocked requests and threat detection

#### Detailed Analytics

* **Usage Trends**: Historical consumption patterns
* **Model Comparison**: Performance across different AI models
* **Geographic Distribution**: Usage by region/location
* **User Segmentation**: Consumption by API key or user

### Usage Breakdown

#### By Time Period

```json theme={"system"}
{
  "daily_usage": {
    "requests": 1250,
    "tokens": {
      "input": 45000,
      "output": 32000,
      "total": 77000
    },
    "cost": 1.85,
    "avg_latency": 420
  },
  "monthly_usage": {
    "requests": 38500,
    "tokens": {
      "input": 1350000,
      "output": 980000,
      "total": 2330000
    },
    "cost": 56.20,
    "avg_latency": 398
  }
}
```

#### By Model

```json theme={"system"}
{
  "model_usage": {
    "gpt-5-nano": {
      "requests": 1250,
      "tokens": 77000,
      "cost": 1.60,
      "avg_latency": 422
    },
    "claude-haiku-4-5": {
      "requests": 200,
      "tokens": 18000,
      "cost": 0.45,
      "avg_latency": 390
    }
  }
}
```

## API Usage Tracking

### Current Availability

#### Developer API - Usage Stats

Get current usage statistics via API:

<Tabs>
  <Tab title="Python">
    ```python theme={"system"}
    import requests
    import os
    from datetime import datetime

    api_key = os.environ.get("PROMPTGUARD_API_KEY")
    base_url = "https://api.promptguard.co/api/v1"

    headers = {
        "X-API-Key": api_key
    }

    # Get current usage statistics
    def get_usage_stats():
        response = requests.get(
            f"{base_url}/usage/stats",
            headers=headers
        )

        if response.status_code == 200:
            stats = response.json()
            print(f"Requests this month: {stats.get('requests_this_month', 0)}")
            print(f"Monthly limit: {stats.get('monthly_limit', 0)}")
            print(f"Requests remaining: {stats.get('requests_remaining', 0)}")
            print(f"Usage percentage: {stats.get('usage_percentage', 0):.1f}%")

            # Check if over limit
            if stats.get('requests_remaining', 0) < 0:
                print("Warning: You've exceeded your monthly limit!")

            return stats
        elif response.status_code == 401:
            print("Error: Invalid API key")
        else:
            print(f"Error: HTTP {response.status_code}")
        return None

    # Example usage
    if __name__ == "__main__":
        stats = get_usage_stats()
        if stats:
            usage_pct = stats.get('usage_percentage', 0)
            if usage_pct > 90:
                print("\nWarning: Consider upgrading your plan or enabling on-demand usage.")
    ```
  </Tab>

  <Tab title="Node.js">
    ```typescript theme={"system"}
    import fetch from 'node-fetch';

    const apiKey = process.env.PROMPTGUARD_API_KEY;
    const baseUrl = 'https://api.promptguard.co/api/v1';

    const headers = {
      'X-API-Key': apiKey
    };

    // Get current usage statistics
    async function getUsageStats() {
      const response = await fetch(`${baseUrl}/usage/stats`, { headers });

      if (response.status === 200) {
        const stats = await response.json();
        console.log(`Requests this month: ${stats.requests_this_month || 0}`);
        console.log(`Monthly limit: ${stats.monthly_limit || 0}`);
        console.log(`Requests remaining: ${stats.requests_remaining || 0}`);
        console.log(`Usage percentage: ${(stats.usage_percentage || 0).toFixed(1)}%`);

        // Check if over limit
        if (stats.requests_remaining < 0) {
          console.log('Warning: You\'ve exceeded your monthly limit!');
        }

        return stats;
      } else if (response.status === 401) {
        console.error('Error: Invalid API key');
      } else {
        console.error(`Error: HTTP ${response.status}`);
      }
      return null;
    }

    // Example usage
    getUsageStats().then(stats => {
      if (stats) {
        const usagePct = stats.usage_percentage || 0;
        if (usagePct > 90) {
          console.log('\nWarning: Consider upgrading your plan or enabling on-demand usage.');
        }
      }
    });
    ```
  </Tab>

  <Tab title="cURL">
    ```bash theme={"system"}
    # Get current usage statistics (developer API - requires API key)
    curl https://api.promptguard.co/api/v1/usage/stats \
      -H "X-API-Key: $PROMPTGUARD_API_KEY"
    ```
  </Tab>
</Tabs>

**Response Format:**

```json theme={"system"}
{
  "requests_this_month": 1250,
  "monthly_limit": 1000,
  "requests_remaining": -250,
  "usage_percentage": 125.0,
  "billing_period": {
    "start_date": "2024-01-01T00:00:00Z",
    "end_date": "2024-02-01T00:00:00Z",
    "days_remaining": 16
  }
}
```

## Cost Management

### Current Dashboard Features

Monitor costs through the dashboard:

1. **Navigate**: [app.promptguard.co](https://app.promptguard.co) → Settings → Usage
2. **View Usage**: See current month's usage and remaining quota
3. **Spending**: Configure on-demand usage and spending limits (Settings → Spending)
4. **Billing**: Access billing information and subscription details (Settings → Billing & Invoices)

### Cost Optimization Tips

* **Model Selection**: Use GPT-3.5-turbo for simple tasks when GPT-4 isn't necessary
* **Prompt Engineering**: Shorter, more efficient prompts reduce token costs
* **Caching**: Reuse responses for similar queries (coming soon)
* **Monitoring**: Track usage patterns to identify optimization opportunities

## Rate Limiting and Quotas

### Current Limits

Usage limits are based on your subscription plan:

| Plan      | Monthly Requests       | Additional Features                                      |
| --------- | ---------------------- | -------------------------------------------------------- |
| **Free**  | 10,000                 | Basic protection, 2 threat types                         |
| **Pro**   | 100,000                | All 14 security detectors, ML detection, custom policies |
| **Scale** | 1,000,000 (soft limit) | Advanced analytics, compliance, unlimited projects       |

### Monitoring Quotas

View your current usage in the dashboard:

1. **Navigate**: [app.promptguard.co](https://app.promptguard.co) → Settings → Usage
2. **Check Usage**: See requests used vs. monthly limit
3. **Enable On-Demand**: If on Pro or Scale, enable on-demand usage to exceed limits
4. **Upgrade**: Upgrade your plan if you need higher base limits

## Historical Data

### Data Retention

| Plan      | Detailed Data | Aggregated Data |
| --------- | ------------- | --------------- |
| **Free**  | 24 hours      | 7 days          |
| **Pro**   | 7 days        | 30 days         |
| **Scale** | 30 days       | 90 days         |

<Note>
  Need longer retention periods? Contact [sales@promptguard.co](mailto:sales@promptguard.co) for enterprise solutions with custom retention policies.
</Note>

## Troubleshooting Usage Tracking

<AccordionGroup>
  <Accordion title="Missing Usage Data">
    **Common Causes:**

    * Requests not properly authenticated
    * API key belongs to different project
    * Data outside retention period

    **Solutions:**

    * Verify API key is correct and active
    * Check that API key belongs to the project you're querying
    * Check request timestamps
    * Contact support for data recovery
  </Accordion>

  <Accordion title="Incorrect Usage Counts">
    **Solutions:**

    * Verify you're looking at the correct project
    * Check date range filters
    * Ensure API key is from the correct project
    * Refresh dashboard to get latest data
  </Accordion>

  <Accordion title="Performance Metrics Anomalies">
    **Solutions:**

    * Check for network issues during measurement period
    * Review security events that might affect latency
    * Analyze request patterns for outliers
    * Check dashboard analytics for detailed breakdowns
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="Dashboard Analytics" icon="chart-line" href="/platform/dashboard">
    Explore the full monitoring dashboard
  </Card>

  <Card title="Interactions" icon="eye" href="https://app.promptguard.co">
    View detailed security events and interactions
  </Card>

  <Card title="Plans & Limits" icon="dollar-sign" href="/pricing">
    Review plan quotas, rate limits, and how usage is calculated
  </Card>

  <Card title="Billing" icon="credit-card" href="https://app.promptguard.co/dashboard/billing">
    Manage your subscription and billing
  </Card>

  <Card title="Best Practices" icon="star" href="/production/best-practices">
    Usage optimization and cost management
  </Card>
</CardGroup>

Need help with usage tracking setup? [Contact support](mailto:support@promptguard.co) for assistance with analytics and reporting.