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

# Statistics

> Get cache hit rate and usage statistics for sandbox code execution results in HopX sandboxes. Monitor cache performance, view hit rates, track cached items, and optimize execution speed. Essential for understanding cache effectiveness and performance tuning. Includes Python and JavaScript SDK examples and REST API endpoints.

Monitor the execution result cache to understand cache performance, optimize your code patterns, and track cache usage over time.

## Overview

HopX caches execution results to improve performance for repeated code executions. Cache statistics help you:

* Monitor cache hit rates
* Track cache size and entry counts
* Optimize code patterns for better caching
* Understand cache effectiveness

<Note>
  The cache stores execution results based on code content and environment. Identical code executions with the same environment variables will hit the cache.
</Note>

## Getting Cache Statistics

Retrieve current cache statistics:

<Tabs>
  <Tab title="Python">
    ```python theme={null}
    from hopx_ai import Sandbox

    sandbox = Sandbox.create(template="code-interpreter")

    # Get cache statistics
    stats = sandbox.cache.stats()

    # Cache data is nested under 'cache' key
    cache_data = stats['cache']
    print(f"Total Hits: {cache_data['total_hits']}")
    print(f"Cache Size: {cache_data['size']}")
    print(f"Max Size: {cache_data['max_size']}")
    print(f"TTL: {cache_data['ttl']}")
    print(f"Timestamp: {stats['timestamp']}")

    sandbox.kill()
    ```
  </Tab>

  <Tab title="JavaScript">
    ```javascript theme={null}
    import { Sandbox } from '@hopx-ai/sdk';

    const sandbox = await Sandbox.create({
      template: 'code-interpreter'
    });

    // Get cache statistics
    const stats = await sandbox.cache.stats();

    // Cache data is nested under 'cache' key
    const cacheData = stats.cache;
    console.log(`Total Hits: ${cacheData.total_hits}`);
    console.log(`Cache Size: ${cacheData.size}`);
    console.log(`Max Size: ${cacheData.max_size}`);
    console.log(`TTL: ${cacheData.ttl}`);
    console.log(`Timestamp: ${stats.timestamp}`);

    await sandbox.kill();
    ```
  </Tab>
</Tabs>

## Understanding Cache Metrics

### Cache Size and Hits

Monitor cache usage and performance:

<Tabs>
  <Tab title="Python">
    ```python theme={null}
    from hopx_ai import Sandbox

    sandbox = Sandbox.create(template="code-interpreter")

    stats = sandbox.cache.stats()
    cache_data = stats['cache']

    print(f"Total Cache Hits: {cache_data['total_hits']}")
    print(f"Current Cache Size: {cache_data['size']}")
    print(f"Max Cache Size: {cache_data['max_size']}")
    print(f"Cache TTL: {cache_data['ttl']}")

    if cache_data['total_hits'] > 100:
        print("✅ Cache is being utilized effectively")
    else:
        print("💡 Consider optimizing code patterns for better caching")

    sandbox.kill()
    ```
  </Tab>

  <Tab title="JavaScript">
    ```javascript theme={null}
    import { Sandbox } from '@hopx-ai/sdk';

    const sandbox = await Sandbox.create({
      template: 'code-interpreter'
    });

    const stats = await sandbox.cache.stats();
    const cacheData = stats.cache;

    console.log(`Total Cache Hits: ${cacheData.total_hits}`);
    console.log(`Current Cache Size: ${cacheData.size}`);
    console.log(`Max Cache Size: ${cacheData.max_size}`);
    console.log(`Cache TTL: ${cacheData.ttl}`);

    if (cacheData.total_hits > 100) {
      console.log('✅ Cache is being utilized effectively');
    } else {
      console.log('💡 Consider optimizing code patterns for better caching');
    }

    await sandbox.kill();
    ```
  </Tab>
</Tabs>

### Cache Size

Monitor cache size to ensure it's not consuming excessive resources:

<Tabs>
  <Tab title="Python">
    ```python theme={null}
    from hopx_ai import Sandbox

    sandbox = Sandbox.create(template="code-interpreter")

    stats = sandbox.cache.stats()
    cache_data = stats['cache']
    cache_size = cache_data['size']
    max_size = cache_data['max_size']

    print(f"Cache Size: {cache_size}")
    print(f"Max Cache Size: {max_size}")
    print(f"Cache TTL: {cache_data['ttl']}")

    if cache_size > max_size * 0.8:
        print("⚠️  Cache size is approaching maximum. Consider clearing if needed.")
    elif cache_size > max_size * 0.5:
        print("Cache size is moderate.")
    else:
        print("Cache size is small.")

    sandbox.kill()
    ```
  </Tab>

  <Tab title="JavaScript">
    ```javascript theme={null}
    import { Sandbox } from '@hopx-ai/sdk';

    const sandbox = await Sandbox.create({
      template: 'code-interpreter'
    });

    const stats = await sandbox.cache.stats();
    const cacheData = stats.cache;
    const cacheSize = cacheData.size;
    const maxSize = cacheData.max_size;

    console.log(`Cache Size: ${cacheSize}`);
    console.log(`Max Cache Size: ${maxSize}`);
    console.log(`Cache TTL: ${cacheData.ttl}`);

    if (cacheSize > maxSize * 0.8) {
      console.log('⚠️  Cache size is approaching maximum. Consider clearing if needed.');
    } else if (cacheSize > maxSize * 0.5) {
      console.log('Cache size is moderate.');
    } else {
      console.log('Cache size is small.');
    }

    await sandbox.kill();
    ```
  </Tab>
</Tabs>

## Monitoring Cache Performance

Track cache performance over time:

<Tabs>
  <Tab title="Python">
    ```python theme={null}
    from hopx_ai import Sandbox
    import time

    sandbox = Sandbox.create(template="code-interpreter")

    # Run some code to generate cache entries
    for i in range(5):
        sandbox.run_code(f"print('Execution {i}')")
        time.sleep(1)

    # Check cache statistics
    stats = sandbox.cache.stats()
    cache_data = stats['cache']

    print("Cache Performance:")
    print(f"  Total Cache Hits: {cache_data['total_hits']}")
    print(f"  Current Cache Size: {cache_data['size']}")
    print(f"  Max Cache Size: {cache_data['max_size']}")
    print(f"  Cache TTL: {cache_data['ttl']}")
    print(f"  Timestamp: {stats['timestamp']}")

    sandbox.kill()
    ```
  </Tab>

  <Tab title="JavaScript">
    ```javascript theme={null}
    import { Sandbox } from '@hopx-ai/sdk';

    const sandbox = await Sandbox.create({
      template: 'code-interpreter'
    });

    // Run some code to generate cache entries
    for (let i = 0; i < 5; i++) {
      await sandbox.runCode(`print('Execution ${i}')`);
      await new Promise(resolve => setTimeout(resolve, 1000));
    }

    // Check cache statistics
    const stats = await sandbox.cache.stats();
    const cacheData = stats.cache;

    console.log('Cache Performance:');
    console.log(`  Total Cache Hits: ${cacheData.total_hits}`);
    console.log(`  Current Cache Size: ${cacheData.size}`);
    console.log(`  Max Cache Size: ${cacheData.max_size}`);
    console.log(`  Cache TTL: ${cacheData.ttl}`);
    console.log(`  Timestamp: ${stats.timestamp}`);

    await sandbox.kill();
    ```
  </Tab>
</Tabs>

## Cache Statistics Response

The cache statistics response includes:

```json theme={null}
{
  "cache": {
    "max_size": 1000,
    "size": 0,
    "total_hits": 0,
    "ttl": "5m0s"
  },
  "timestamp": "2025-01-27T19:43:55Z"
}
```

### Field Descriptions

* **`cache.max_size`**: Maximum cache size limit
* **`cache.size`**: Current cache size
* **`cache.total_hits`**: Total number of cache hits (cached results reused)
* **`cache.ttl`**: Time-to-live for cache entries
* **`timestamp`**: Timestamp when the statistics were retrieved

## Use Cases

### Optimizing for Cache

Test cache effectiveness with repeated executions:

<Tabs>
  <Tab title="Python">
    ```python theme={null}
    from hopx_ai import Sandbox
    import time

    sandbox = Sandbox.create(template="code-interpreter")

    # Initial execution (cache miss)
    code = "result = sum(range(1000000)); print(f'Sum: {result}')"
    sandbox.run_code(code)

    # Get initial stats
    initial_stats = sandbox.cache.stats()
    initial_hits = initial_stats['cache']['total_hits']
    print(f"After first execution - Total Hits: {initial_hits}")

    # Repeat same code (should hit cache)
    sandbox.run_code(code)

    # Check stats after repeat
    final_stats = sandbox.cache.stats()
    final_hits = final_stats['cache']['total_hits']
    print(f"After repeat execution - Total Hits: {final_hits}")

    if final_hits > initial_hits:
        print("✅ Cache hit confirmed - repeated execution used cached result")
    else:
        print("⚠️  No cache hit - execution may have been different")

    sandbox.kill()
    ```
  </Tab>

  <Tab title="JavaScript">
    ```javascript theme={null}
    import { Sandbox } from '@hopx-ai/sdk';

    const sandbox = await Sandbox.create({
      template: 'code-interpreter'
    });

    // Initial execution (cache miss)
    const code = "result = sum(range(1000000)); print(f'Sum: {result}')";
    await sandbox.runCode(code);

    // Get initial stats
    const initialStats = await sandbox.cache.stats();
    const initialHits = initialStats.cache.total_hits;
    console.log(`After first execution - Total Hits: ${initialHits}`);

    // Repeat same code (should hit cache)
    await sandbox.runCode(code);

    // Check stats after repeat
    const finalStats = await sandbox.cache.stats();
    const finalHits = finalStats.cache.total_hits;
    console.log(`After repeat execution - Total Hits: ${finalHits}`);

    if (finalHits > initialHits) {
      console.log('✅ Cache hit confirmed - repeated execution used cached result');
    } else {
      console.log('⚠️  No cache hit - execution may have been different');
    }

    await sandbox.kill();
    ```
  </Tab>
</Tabs>

### Monitoring Cache Growth

Track how cache grows over time:

<Tabs>
  <Tab title="Python">
    ```python theme={null}
    from hopx_ai import Sandbox
    import time

    sandbox = Sandbox.create(template="code-interpreter")

    # Monitor cache growth
    for i in range(10):
        # Execute different code each time
        sandbox.run_code(f"print('Execution {i}: {i * 10}')")
        
        stats = sandbox.cache.stats()
        cache_data = stats['cache']
        print(f"After execution {i+1}: Size={cache_data['size']}, Hits={cache_data['total_hits']}")
        
        time.sleep(0.5)

    sandbox.kill()
    ```
  </Tab>

  <Tab title="JavaScript">
    ```javascript theme={null}
    import { Sandbox } from '@hopx-ai/sdk';

    const sandbox = await Sandbox.create({
      template: 'code-interpreter'
    });

    // Monitor cache growth
    for (let i = 0; i < 10; i++) {
      // Execute different code each time
      await sandbox.runCode(`print('Execution ${i}: ${i * 10}')`);
      
      const stats = await sandbox.cache.stats();
      const cacheData = stats.cache;
      console.log(`After execution ${i+1}: Size=${cacheData.size}, Hits=${cacheData.total_hits}`);
      
      await new Promise(resolve => setTimeout(resolve, 500));
    }

    await sandbox.kill();
    ```
  </Tab>
</Tabs>

## Best Practices

<Tip>
  **Monitor total hits** to understand cache effectiveness. A high number of total hits indicates good cache utilization.
</Tip>

<Tip>
  **Cache works best with deterministic code**. Code that produces the same output for the same input will benefit most from caching.
</Tip>

<Warning>
  **Cache size can grow over time**. Monitor cache size and clear it periodically if it becomes too large.
</Warning>

<Tip>
  **Environment variables affect caching**. Code with different environment variables will have separate cache entries.
</Tip>

## API Reference

### Python SDK

* `sandbox.cache.stats(*, timeout=None)` - Get cache statistics

### JavaScript SDK

* `sandbox.cache.stats()` - Get cache statistics

### API Endpoint

* **GET** `/cache/stats` - Get execution cache statistics

## Related

* **[Clearing Cache](/core-concepts/cache/clearing)** - Clear cache to free memory
* **SDK**: [sandbox.cache.stats()](/sdk/python/cache#stats) - Python SDK method
* **API**: [GET /cache/stats](/api/vm-agent/get-cache-stats) - VM Agent API endpoint

## Next Steps

* Learn about [Clearing Cache](/core-concepts/cache/clearing) to free memory

* Review [Code Execution](/core-concepts/code-execution/synchronous) to see cached results

* [Clearing Cache](/core-concepts/cache/clearing) - Clear the execution cache

* **[CLI System Commands](/cli/commands/system)** - View cache statistics from CLI