---
title: "oz0 usage cache"
description: "Usage and flags for oz0 usage cache."
canonical_url: "https://docs.oz0.ai/reference/cli/oz0/usage/cache"
---
# oz0 usage cache

> Usage and flags for oz0 usage cache.

For: Operators and developers looking up a command.

Where a provider caches prompts, the gateway records for every call how much of its input was read from the cache and what that saved at the input price after the cache's write premium.

For a call that read less than it could have, it records why:

- first_call.
- expired: the time since the job's previous call outlasted the cache's lifetime, often an approval wait.
- member_changed: a pooled provider record's other member served the call.
- tools_changed, model_changed, instructions_changed, compacted or history_changed.
- not_cached: the provider read nothing although nothing changed.
- not_asked: the tenant's cache is off.
- rewarm: the platform's own request that warmed the cache again after a wait.

The hit rate is cache reads over cacheable input. Figures are per agent and model, or per team with --by-team (teams below works-council mode's threshold are folded into "other teams"), never per person. Calls made before this was recorded are not in the figures.

## Usage

```bash
oz0 usage cache [flags]
```

## Flags

<table>
<thead>
  <tr>
    <th>
      Flag
    </th>
    
    <th>
      Type
    </th>
    
    <th>
      Default
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        --agent
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      
    </td>
    
    <td>
      only this agent
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --by-team
      </code>
    </td>
    
    <td>
      bool
    </td>
    
    <td>
      
    </td>
    
    <td>
      group by the jobs' team as well
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --causes
      </code>
    </td>
    
    <td>
      bool
    </td>
    
    <td>
      
    </td>
    
    <td>
      show the misses per agent and cause, with what each cost
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --json
      </code>
    </td>
    
    <td>
      bool
    </td>
    
    <td>
      
    </td>
    
    <td>
      print JSON instead of a table
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --since
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      <code>
        30d
      </code>
    </td>
    
    <td>
      from when: a duration back such as 7d or 24h, or an RFC 3339 time
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --team
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      
    </td>
    
    <td>
      only this team (shown only while it has as many people as works-council mode asks)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --tenant
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      <code>
        the default tenant
      </code>
    </td>
    
    <td>
      the tenant
    </td>
  </tr>
</tbody>
</table>

## Inherited flags

<table>
<thead>
  <tr>
    <th>
      Flag
    </th>
    
    <th>
      Type
    </th>
    
    <th>
      Default
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        --context
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      <code>
        $OZ0_CONTEXT or &lt;config dir>/orchestrator-zero/context.json
      </code>
    </td>
    
    <td>
      CLI context file written by server init
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --log-level
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      <code>
        info
      </code>
    </td>
    
    <td>
      log level: debug, info, warn or error
    </td>
  </tr>
</tbody>
</table>

See [all `oz0` commands](https://docs.oz0.ai/reference/cli/oz0) and the [global flags](https://docs.oz0.ai/reference/cli/oz0#global-flags).


## Sitemap

See the full [sitemap](https://docs.oz0.ai/sitemap.md) for all pages.