# GET /v1/account/usage

Retrieve detailed usage statistics for your organization, including request counts, credit consumption, and performance metrics.

## 📋 Overview

| Property | Value |
|----------|-------|
| **Method** | `GET` |
| **Endpoint** | `https://api.influtics.com/v1/account/usage` |
| **Auth Required** | ✅ Yes |
| **Credits Cost** | 🆓 Free |

## 🔐 Headers

```
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
```

## 📝 Request

### Basic Request

```bash
curl -X GET https://api.influtics.com/v1/account/usage \
  -H "Authorization: Bearer your_api_key_here" \
  -H "Content-Type: application/json"
```

### No Parameters Required
This endpoint doesn't require any query parameters or request body.

## ✅ Response

### Success Response (200 OK)

```json
{
  "success": true,
  "data": {
    "usage_history": [
      {
        "organization_id": "5ec3a68c-a058-4760-81b8-54f376e34f79",
        "created_at": "2025-06-23T16:15:50.971544+00:00",
        "total_requests": 1,
        "successful_requests": 1,
        "error_requests": 0,
        "total_credits_used": 0,
        "avg_response_time": 2836,
        "unique_api_keys": 1
      },
      {
        "organization_id": "5ec3a68c-a058-4760-81b8-54f376e34f79",
        "created_at": "2025-06-23T16:14:18.646295+00:00",
        "total_requests": 1,
        "successful_requests": 1,
        "error_requests": 0,
        "total_credits_used": 0,
        "avg_response_time": 2462,
        "unique_api_keys": 1
      }
    ],
    "summary": {
      "total_requests_30_days": 5,
      "total_credits_30_days": 0
    }
  },
  "meta": {
    "processing_time_ms": 1077,
    "request_id": "bfb57e03-b290-4264-9f6b-e6cc03674916"
  }
}
```

## 📊 Response Fields

### `data.usage_history[]`
Array of daily usage statistics (up to 30 days):

| Field | Type | Description |
|-------|------|-------------|
| `organization_id` | `string` | Your organization's unique identifier |
| `created_at` | `string` | ISO 8601 timestamp of the usage record |
| `total_requests` | `number` | Total API requests made on this day |
| `successful_requests` | `number` | Number of successful API requests |
| `error_requests` | `number` | Number of failed API requests |
| `total_credits_used` | `number` | Credits consumed on this day |
| `avg_response_time` | `number` | Average response time in milliseconds |
| `unique_api_keys` | `number` | Number of different API keys used |

### `data.summary`
30-day summary statistics:

| Field | Type | Description |
|-------|------|-------------|
| `total_requests_30_days` | `number` | Total requests in the last 30 days |
| `total_credits_30_days` | `number` | Total credits used in the last 30 days |

### `meta`
Request metadata:

| Field | Type | Description |
|-------|------|-------------|
| `processing_time_ms` | `number` | Time taken to process the request |
| `request_id` | `string` | Unique identifier for this request |

## ⚠️ Error Responses

All errors share the standard envelope `{ success: false, error: { code, message, request_id, ... } }`. The table below lists every documented `code` and the conditions that trigger it.

| Status | `code` | Trigger | Additional `error` fields |
|--------|--------|---------|---------------------------|
| `401` | `INVALID_API_KEY` | The `Authorization: Bearer` API key is missing, empty, revoked, or unknown | — |
| `403` | `INSUFFICIENT_PERMISSIONS` | The API key is valid but the caller is not a member of the org whose usage is being requested | — |
| `500` | `INTERNAL_ERROR` | Unexpected DB or service failure (e.g. `organization_subscription_cache` lookup errors, transient Supabase outage) | — |

## 💡 Usage Examples

### JavaScript/Node.js
```javascript
async function getUsageStats() {
  try {
    const response = await fetch('https://api.influtics.com/v1/account/usage', {
      headers: {
        'Authorization': 'Bearer your_api_key_here',
        'Content-Type': 'application/json'
      }
    });
    
    const data = await response.json();
    
    if (data.success) {
      console.log('30-day requests:', data.data.summary.total_requests_30_days);
      console.log('30-day credits:', data.data.summary.total_credits_30_days);
    }
  } catch (error) {
    console.error('Error fetching usage:', error);
  }
}
```

### Python
```python
import requests

def get_usage_stats():
    headers = {
        'Authorization': 'Bearer your_api_key_here',
        'Content-Type': 'application/json'
    }
    
    response = requests.get('https://api.influtics.com/v1/account/usage', headers=headers)
    
    if response.status_code == 200:
        data = response.json()
        print(f"30-day requests: {data['data']['summary']['total_requests_30_days']}")
        print(f"30-day credits: {data['data']['summary']['total_credits_30_days']}")
    else:
        print(f"Error: {response.status_code}")
```

## 📈 Use Cases

- **Monitor API Usage**: Track your daily and monthly API consumption
- **Performance Analysis**: Monitor average response times
- **Budget Planning**: Track credit usage for billing purposes
- **Error Monitoring**: Identify patterns in failed requests
- **Team Analytics**: Monitor API key usage across your organization

---

**Related**: [Track Video →](../videos/track) | [Get Video Stats →](../videos/stats)