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

# Account Statistics

> Retrieve comprehensive usage statistics for your Scanova account — including QR code counts, scan activity, and feature utilization. Use the optional fields parameter to fetch only the specific metrics you need. Authentication required.

## Description

This endpoint provides **aggregated statistics** for your Scanova account.\
It’s ideal for **dashboard overviews**, **usage monitoring**, or **account-level analytics** integrations.

You can retrieve all metrics at once or request specific fields (like only total scans or dynamic QR count) to optimize performance.

### Available Field Values

| Field                     | Description                                           |
| :------------------------ | :---------------------------------------------------- |
| `total_qr_count`          | Total number of QR codes in the account               |
| `static_qr_count`         | Count of static QR codes                              |
| `dynamic_qr_count`        | Count of dynamic QR codes                             |
| `total_scan_count`        | Total number of scans across all QR codes             |
| `total_designer_qr_count` | Number of QR codes using custom design templates      |
| `custom_domain_count`     | Number of QR codes using custom domains               |
| `lead_list_count`         | Total number of lead lists created                    |
| `shared_user_count`       | Number of shared users (collaborators) in the account |

## Examples

### **Get All Account Statistics**

```bash theme={null}
curl -X GET "https://management.scanova.io/auth/stats/" \
  -H "Authorization: YOUR_API_KEY"
```

### **Get Filtered Statistics**

```bash theme={null}
curl -X GET "https://management.scanova.io/auth/stats/?fields=total_qr_count,total_scan_count,lead_list_count" \
  -H "Authorization: YOUR_API_KEY"
```

### **Get QR Code Counts Only**

```bash theme={null}
curl -X GET "https://management.scanova.io/auth/stats/?fields=total_qr_count,static_qr_count,dynamic_qr_count" \
  -H "Authorization: YOUR_API_KEY"
```

### **Get Usage Metrics**

```bash theme={null}
curl -X GET "https://management.scanova.io/auth/stats/?fields=total_scan_count,total_designer_qr_count,custom_domain_count" \
  -H "Authorization: YOUR_API_KEY"
```

## Response Structure

### **Success Response (200 OK)**

```json theme={null}
{
  "total_qr_count": 150,
  "static_qr_count": 25,
  "dynamic_qr_count": 125,
  "total_scan_count": 5420,
  "total_designer_qr_count": 45,
  "custom_domain_count": 12,
  "lead_list_count": 8,
  "shared_user_count": 5
}
```

### **Filtered Response Example**

When using `fields=total_qr_count,total_scan_count,lead_list_count`:

```json theme={null}
{
  "total_qr_count": 150,
  "total_scan_count": 5420,
  "lead_list_count": 8
}
```

## Schema

| Field                     | Type      | Example | Description                              |
| :------------------------ | :-------- | :------ | :--------------------------------------- |
| `total_qr_count`          | `integer` | `150`   | Total QR codes in the account            |
| `static_qr_count`         | `integer` | `25`    | Count of static QR codes                 |
| `dynamic_qr_count`        | `integer` | `125`   | Count of dynamic QR codes                |
| `total_scan_count`        | `integer` | `5420`  | Total scans recorded                     |
| `total_designer_qr_count` | `integer` | `45`    | Number of custom-designed QR codes       |
| `custom_domain_count`     | `integer` | `12`    | QR codes with custom domains             |
| `lead_list_count`         | `integer` | `8`     | Total lead lists created                 |
| `shared_user_count`       | `integer` | `5`     | Shared users associated with the account |

## Integration Examples

### **JavaScript - Get Account Statistics**

```javascript theme={null}
async function getAccountStats(fields = null) {
  try {
    let url = "https://management.scanova.io/auth/stats/";
    if (fields) {
      url += `?fields=${fields.join(',')}`;
    }
    
    const response = await fetch(url, {
      method: 'GET',
      headers: {
        'Authorization': 'YOUR_API_KEY',
        'Content-Type': 'application/json'
      }
    });
    
    if (response.ok) {
      const stats = await response.json();
      return stats;
    } else {
      throw new Error('Failed to fetch account statistics');
    }
  } catch (error) {
    console.error('Error fetching account statistics:', error);
    return null;
  }
}

// Usage - Get all statistics
const allStats = await getAccountStats();
console.log('All statistics:', allStats);

// Usage - Get filtered statistics
const qrStats = await getAccountStats(['total_qr_count', 'static_qr_count', 'dynamic_qr_count']);
console.log('QR Code statistics:', qrStats);

// Usage - Get usage metrics
const usageStats = await getAccountStats(['total_scan_count', 'total_designer_qr_count', 'custom_domain_count']);
console.log('Usage statistics:', usageStats);
```

### **Python - Get Account Statistics**

```python theme={null}
import requests

def get_account_stats(fields=None):
    url = "https://management.scanova.io/auth/stats/"
    headers = {"Authorization": "YOUR_API_KEY"}
    
    params = {}
    if fields:
        params['fields'] = ','.join(fields)
    
    try:
        response = requests.get(url, headers=headers, params=params)
        response.raise_for_status()
        return response.json()
    except requests.exceptions.RequestException as e:
        print(f"Error fetching account statistics: {e}")
        return None

def display_account_overview():
    """Display a comprehensive account overview"""
    stats = get_account_stats()
    if stats:
        print("=== Account Overview ===")
        print(f"Total QR Codes: {stats.get('total_qr_count', 0)}")
        print(f"  - Static: {stats.get('static_qr_count', 0)}")
        print(f"  - Dynamic: {stats.get('dynamic_qr_count', 0)}")
        print(f"Total Scans: {stats.get('total_scan_count', 0)}")
        print(f"Designer QR Codes: {stats.get('total_designer_qr_count', 0)}")
        print(f"Custom Domains: {stats.get('custom_domain_count', 0)}")
        print(f"Lead Lists: {stats.get('lead_list_count', 0)}")
        print(f"Shared Users: {stats.get('shared_user_count', 0)}")
        
        # Calculate usage percentages
        total_qr = stats.get('total_qr_count', 0)
        if total_qr > 0:
            designer_pct = (stats.get('total_designer_qr_count', 0) / total_qr) * 100
            custom_domain_pct = (stats.get('custom_domain_count', 0) / total_qr) * 100
            print(f"\n=== Usage Analysis ===")
            print(f"Designer QR Codes: {designer_pct:.1f}% of total")
            print(f"Custom Domains: {custom_domain_pct:.1f}% of total")
    
    return stats

def get_qr_code_breakdown():
    """Get detailed QR code statistics"""
    return get_account_stats(['total_qr_count', 'static_qr_count', 'dynamic_qr_count'])

def get_usage_metrics():
    """Get usage and performance metrics"""
    return get_account_stats(['total_scan_count', 'total_designer_qr_count', 'custom_domain_count'])

# Usage
display_account_overview()
qr_breakdown = get_qr_code_breakdown()
usage_metrics = get_usage_metrics()
```

### **PHP - Get Account Statistics**

```php theme={null}
<?php
function getAccountStats($fields = null) {
    $url = "https://management.scanova.io/auth/stats/";
    $headers = [
        "Authorization: YOUR_API_KEY",
        "Content-Type: application/json"
    ];
    
    $params = [];
    if ($fields) {
        $params['fields'] = implode(',', $fields);
    }
    
    $queryString = http_build_query($params);
    if ($queryString) {
        $url .= '?' . $queryString;
    }
    
    $ch = curl_init();
    curl_setopt($ch, CURLOPT_URL, $url);
    curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    
    $response = curl_exec($ch);
    $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);
    
    if ($httpCode === 200) {
        return json_decode($response, true);
    } else {
        echo "Error fetching account statistics: " . $response;
        return null;
    }
}

function displayAccountOverview() {
    $stats = getAccountStats();
    if ($stats) {
        echo "=== Account Overview ===\n";
        echo "Total QR Codes: " . ($stats['total_qr_count'] ?? 0) . "\n";
        echo "  - Static: " . ($stats['static_qr_count'] ?? 0) . "\n";
        echo "  - Dynamic: " . ($stats['dynamic_qr_count'] ?? 0) . "\n";
        echo "Total Scans: " . ($stats['total_scan_count'] ?? 0) . "\n";
        echo "Designer QR Codes: " . ($stats['total_designer_qr_count'] ?? 0) . "\n";
        echo "Custom Domains: " . ($stats['custom_domain_count'] ?? 0) . "\n";
        echo "Lead Lists: " . ($stats['lead_list_count'] ?? 0) . "\n";
        echo "Shared Users: " . ($stats['shared_user_count'] ?? 0) . "\n";
        
        // Calculate usage percentages
        $totalQr = $stats['total_qr_count'] ?? 0;
        if ($totalQr > 0) {
            $designerPct = (($stats['total_designer_qr_count'] ?? 0) / $totalQr) * 100;
            $customDomainPct = (($stats['custom_domain_count'] ?? 0) / $totalQr) * 100;
            echo "\n=== Usage Analysis ===\n";
            echo "Designer QR Codes: " . number_format($designerPct, 1) . "% of total\n";
            echo "Custom Domains: " . number_format($customDomainPct, 1) . "% of total\n";
        }
    }
    
    return $stats;
}

function getQrCodeBreakdown() {
    return getAccountStats(['total_qr_count', 'static_qr_count', 'dynamic_qr_count']);
}

function getUsageMetrics() {
    return getAccountStats(['total_scan_count', 'total_designer_qr_count', 'custom_domain_count']);
}

// Usage
displayAccountOverview();
$qrBreakdown = getQrCodeBreakdown();
$usageMetrics = getUsageMetrics();
?
```

## Use Cases

* 📊 **Admin dashboards:** Display live account metrics like total scans and QR creation trends.
* 🧮 **Usage-based billing:** Validate active and dynamic QR usage for plan-based limits.
* 🧠 **Insights & analytics:** Track QR code adoption and engagement performance across users.
* ⚙️ **Automation scripts:** Integrate account metrics into internal monitoring tools or CRMs.

###


## OpenAPI

````yaml GET /auth/stats/
openapi: 3.0.0
info:
  title: Scanova API - Analytics
  description: >-
    Analytics endpoints for retrieving QR code scan data, statistics, and
    exporting analytics reports. These endpoints provide comprehensive insights
    into QR code performance, user behavior, and geographic distribution.
  version: 1.0.0
servers:
  - url: https://management.scanova.io
    description: Scanova Management API Server
security:
  - apiKeyAuth: []
paths:
  /auth/stats/:
    get:
      tags:
        - Analytics
      summary: Get Account Statistics
      description: >-
        Retrieves comprehensive account statistics including QR code counts,
        scan counts, and feature usage statistics. Use the fields parameter to
        filter which statistics to return.
      parameters:
        - name: fields
          in: query
          required: false
          description: >-
            Comma-separated list of fields to include in the response. If not
            specified, all fields are returned.
          schema:
            type: string
            enum:
              - total_qr_count
              - static_qr_count
              - dynamic_qr_count
              - total_scan_count
              - total_designer_qr_count
              - custom_domain_count
              - lead_list_count
              - shared_user_count
          example: total_qr_count,total_scan_count,lead_list_count
      responses:
        '200':
          description: Account statistics retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  total_qr_count:
                    type: integer
                    description: Total number of QR codes in the account
                    example: 150
                  static_qr_count:
                    type: integer
                    description: Number of static QR codes
                    example: 25
                  dynamic_qr_count:
                    type: integer
                    description: Number of dynamic QR codes
                    example: 125
                  total_scan_count:
                    type: integer
                    description: Total number of scans across all QR codes
                    example: 5420
                  total_designer_qr_count:
                    type: integer
                    description: Number of QR codes with custom designs
                    example: 45
                  custom_domain_count:
                    type: integer
                    description: Number of QR codes using custom domains
                    example: 12
                  lead_list_count:
                    type: integer
                    description: Number of lead lists in the account
                    example: 8
                  shared_user_count:
                    type: integer
                    description: Number of shared users in the account
                    example: 5
        '401':
          description: Unauthorized - Invalid API key
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: string
                    example: Authentication credentials were not provided.
      security:
        - apiKeyAuth: []
components:
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: header
      name: Authorization
      description: >-
        API key authentication. Enter your API key directly in the Authorization
        header.

````