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

# Resource Usage

> The Resource Usage API reports how often a given AI instruction, knowledge base item, or action was available to the AI and how often it was actually applied.

The Resource Usage API is a reverse lookup over AI-reply usage: given an action,
instruction, or knowledge base item, it answers **"where was this used?"** and
**"how often does it fire?"**.

## How Usage Is Tracked

Every AI reply records which resources were involved, with two usage kinds:

* **Available** — the resource was in the AI's context for the reply. For
  instructions and knowledge base items, this means it was eligible to be used.
* **Applied** ("used") — the resource was actually applied: an instruction or
  knowledge base item cited in the reply, or an action invoked. Actions are
  always recorded as applied (they only appear when called).

Comparing applied vs. available gives an **apply-rate** for instructions and
knowledge base items.

## Resource Types

The `resource_type` path parameter selects what to look up:

* `instruction` — an AI instruction / behavior
* `knowledge` — a knowledge base item
* `action` — a tool the AI can call

## Scopes

Both endpoints require the resource's own read scope plus `chat-sessions:read`
(the responses expose conversation data — session ids, ticket numbers, last
message):

* `instruction` / `knowledge` → `training:read` + `chat-sessions:read`
* `action` → `actions:read` + `chat-sessions:read`

## Available Endpoints

<CardGroup>
  <Card title="Get Usage Summary" icon="chart-simple" href="./usage-summary">
    Aggregate available / applied counts for a resource
  </Card>

  <Card title="List Conversations" icon="list" href="./conversations">
    List the conversations a resource was used in
  </Card>
</CardGroup>
