---
title: "useUsage"
description: "useUsage, auto-imported in the app: its options, return value and types."
canonical_url: "https://nuxt-backend.dev/docs/reference/api/use-usage"
---
# useUsage

## Interfaces

### UseUsageOptions

Defined in: [src/runtime/vue/composables/use-usage.ts](https://github.com/qruto/nuxt-backend/blob/main/src/runtime/vue/composables/use-usage.ts)

#### Properties

<table>
<thead>
  <tr>
    <th>
      Property
    </th>
    
    <th>
      Type
    </th>
    
    <th>
      Description
    </th>
    
    <th>
      Defined in
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <a id="meter">
        
      </a>
      
       <code>
        meter?
      </code>
    </td>
    
    <td>
      <code>
        MaybeRefOrGetter
      </code>
      
      <<code>
        string
      </code>
      
       | <code>
        undefined
      </code>
      
      >
    </td>
    
    <td>
      Which meter's history to read (reactive): a configured credit-meter name (<code>
        'credits'
      </code>
      
      ) or a raw meter id. Omit for every metered event.
    </td>
    
    <td>
      <a href="https://github.com/qruto/nuxt-backend/blob/main/src/runtime/vue/composables/use-usage.ts" rel="nofollow">
        src/runtime/vue/composables/use-usage.ts
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      <a id="api">
        
      </a>
      
       <code>
        api?
      </code>
    </td>
    
    <td>
      <a href="https://nuxt-backend.dev/docs/reference/api/use-billing#billingapi">
        <code>
          BillingApi
        </code>
      </a>
    </td>
    
    <td>
      Override the injected <code>
        api.billing
      </code>
      
       namespace.
    </td>
    
    <td>
      <a href="https://github.com/qruto/nuxt-backend/blob/main/src/runtime/vue/composables/use-usage.ts" rel="nofollow">
        src/runtime/vue/composables/use-usage.ts
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      <a id="limit">
        
      </a>
      
       <code>
        limit?
      </code>
    </td>
    
    <td>
      <code>
        MaybeRefOrGetter
      </code>
      
      <<code>
        number
      </code>
      
       | <code>
        undefined
      </code>
      
      >
    </td>
    
    <td>
      Events per page (reactive). Defaults to the provider's own page size.
    </td>
    
    <td>
      <a href="https://github.com/qruto/nuxt-backend/blob/main/src/runtime/vue/composables/use-usage.ts" rel="nofollow">
        src/runtime/vue/composables/use-usage.ts
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      <a id="immediate">
        
      </a>
      
       <code>
        immediate?
      </code>
    </td>
    
    <td>
      <code>
        boolean
      </code>
    </td>
    
    <td>
      Load the first page on mount. Default <code>
        true
      </code>
      
      .
    </td>
    
    <td>
      <a href="https://github.com/qruto/nuxt-backend/blob/main/src/runtime/vue/composables/use-usage.ts" rel="nofollow">
        src/runtime/vue/composables/use-usage.ts
      </a>
    </td>
  </tr>
</tbody>
</table>

---

### UseUsageReturn

Defined in: [src/runtime/vue/composables/use-usage.ts](https://github.com/qruto/nuxt-backend/blob/main/src/runtime/vue/composables/use-usage.ts)

#### Properties

<table>
<thead>
  <tr>
    <th>
      Property
    </th>
    
    <th>
      Type
    </th>
    
    <th>
      Description
    </th>
    
    <th>
      Defined in
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <a id="events">
        
      </a>
      
       <code>
        events
      </code>
    </td>
    
    <td>
      <code>
        Ref
      </code>
      
      <<a href="https://nuxt-backend.dev/docs/reference/api/use-billing#usageevent">
        <code>
          UsageEvent
        </code>
      </a>
      
      <span>
        
      </span>
      
       | <code>
        undefined
      </code>
      
      >
    </td>
    
    <td>
      The current page of usage events — <code>
        undefined
      </code>
      
       until the first load.
    </td>
    
    <td>
      <a href="https://github.com/qruto/nuxt-backend/blob/main/src/runtime/vue/composables/use-usage.ts" rel="nofollow">
        src/runtime/vue/composables/use-usage.ts
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      <a id="page">
        
      </a>
      
       <code>
        page
      </code>
    </td>
    
    <td>
      <code>
        Ref
      </code>
      
      <<code>
        number
      </code>
      
      >
    </td>
    
    <td>
      The page being shown; provider page numbers start at 1.
    </td>
    
    <td>
      <a href="https://github.com/qruto/nuxt-backend/blob/main/src/runtime/vue/composables/use-usage.ts" rel="nofollow">
        src/runtime/vue/composables/use-usage.ts
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      <a id="total">
        
      </a>
      
       <code>
        total
      </code>
    </td>
    
    <td>
      <code>
        ComputedRef
      </code>
      
      <<code>
        number
      </code>
      
       | <code>
        undefined
      </code>
      
      >
    </td>
    
    <td>
      Total events across all pages, when the provider reported it.
    </td>
    
    <td>
      <a href="https://github.com/qruto/nuxt-backend/blob/main/src/runtime/vue/composables/use-usage.ts" rel="nofollow">
        src/runtime/vue/composables/use-usage.ts
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      <a id="pagecount">
        
      </a>
      
       <code>
        pageCount
      </code>
    </td>
    
    <td>
      <code>
        ComputedRef
      </code>
      
      <<code>
        number
      </code>
      
       | <code>
        undefined
      </code>
      
      >
    </td>
    
    <td>
      Number of pages, when the provider reported it.
    </td>
    
    <td>
      <a href="https://github.com/qruto/nuxt-backend/blob/main/src/runtime/vue/composables/use-usage.ts" rel="nofollow">
        src/runtime/vue/composables/use-usage.ts
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      <a id="units">
        
      </a>
      
       <code>
        units
      </code>
    </td>
    
    <td>
      <code>
        ComputedRef
      </code>
      
      <<code>
        number
      </code>
      
       | <code>
        undefined
      </code>
      
      >
    </td>
    
    <td>
      Units consumed on the page in view, when the events carry them.
    </td>
    
    <td>
      <a href="https://github.com/qruto/nuxt-backend/blob/main/src/runtime/vue/composables/use-usage.ts" rel="nofollow">
        src/runtime/vue/composables/use-usage.ts
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      <a id="hasmore">
        
      </a>
      
       <code>
        hasMore
      </code>
    </td>
    
    <td>
      <code>
        ComputedRef
      </code>
      
      <<code>
        boolean
      </code>
      
      >
    </td>
    
    <td>
      Whether a further page exists.
    </td>
    
    <td>
      <a href="https://github.com/qruto/nuxt-backend/blob/main/src/runtime/vue/composables/use-usage.ts" rel="nofollow">
        src/runtime/vue/composables/use-usage.ts
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      <a id="hasprevious">
        
      </a>
      
       <code>
        hasPrevious
      </code>
    </td>
    
    <td>
      <code>
        ComputedRef
      </code>
      
      <<code>
        boolean
      </code>
      
      >
    </td>
    
    <td>
      Whether an earlier page exists.
    </td>
    
    <td>
      <a href="https://github.com/qruto/nuxt-backend/blob/main/src/runtime/vue/composables/use-usage.ts" rel="nofollow">
        src/runtime/vue/composables/use-usage.ts
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      <a id="isloading">
        
      </a>
      
       <code>
        isLoading
      </code>
    </td>
    
    <td>
      <code>
        ComputedRef
      </code>
      
      <<code>
        boolean
      </code>
      
      >
    </td>
    
    <td>
      Whether a load is in flight.
    </td>
    
    <td>
      <a href="https://github.com/qruto/nuxt-backend/blob/main/src/runtime/vue/composables/use-usage.ts" rel="nofollow">
        src/runtime/vue/composables/use-usage.ts
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      <a id="error">
        
      </a>
      
       <code>
        error
      </code>
    </td>
    
    <td>
      <code>
        Ref
      </code>
      
      <<code>
        string
      </code>
      
       | <code>
        null
      </code>
      
      >
    </td>
    
    <td>
      Message of the last failed load, <code>
        null
      </code>
      
       otherwise. Loads never reject.
    </td>
    
    <td>
      <a href="https://github.com/qruto/nuxt-backend/blob/main/src/runtime/vue/composables/use-usage.ts" rel="nofollow">
        src/runtime/vue/composables/use-usage.ts
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      <a id="refresh">
        
      </a>
      
       <code>
        refresh
      </code>
    </td>
    
    <td>
      () => <code>
        Promise
      </code>
      
      <<code>
        void
      </code>
      
      >
    </td>
    
    <td>
      Reload the current page.
    </td>
    
    <td>
      <a href="https://github.com/qruto/nuxt-backend/blob/main/src/runtime/vue/composables/use-usage.ts" rel="nofollow">
        src/runtime/vue/composables/use-usage.ts
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      <a id="next">
        
      </a>
      
       <code>
        next
      </code>
    </td>
    
    <td>
      () => <code>
        Promise
      </code>
      
      <<code>
        void
      </code>
      
      >
    </td>
    
    <td>
      Load the next page (no-op at the end).
    </td>
    
    <td>
      <a href="https://github.com/qruto/nuxt-backend/blob/main/src/runtime/vue/composables/use-usage.ts" rel="nofollow">
        src/runtime/vue/composables/use-usage.ts
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      <a id="previous">
        
      </a>
      
       <code>
        previous
      </code>
    </td>
    
    <td>
      () => <code>
        Promise
      </code>
      
      <<code>
        void
      </code>
      
      >
    </td>
    
    <td>
      Load the previous page (no-op on page 1).
    </td>
    
    <td>
      <a href="https://github.com/qruto/nuxt-backend/blob/main/src/runtime/vue/composables/use-usage.ts" rel="nofollow">
        src/runtime/vue/composables/use-usage.ts
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      <a id="goto">
        
      </a>
      
       <code>
        goTo
      </code>
    </td>
    
    <td>
      (<code>
        page
      </code>
      
      ) => <code>
        Promise
      </code>
      
      <<code>
        void
      </code>
      
      >
    </td>
    
    <td>
      Jump to a page number.
    </td>
    
    <td>
      <a href="https://github.com/qruto/nuxt-backend/blob/main/src/runtime/vue/composables/use-usage.ts" rel="nofollow">
        src/runtime/vue/composables/use-usage.ts
      </a>
    </td>
  </tr>
</tbody>
</table>

## Functions

### useUsage()

```ts
function useUsage(options?): UseUsageReturn;
```

Defined in: [src/runtime/vue/composables/use-usage.ts](https://github.com/qruto/nuxt-backend/blob/main/src/runtime/vue/composables/use-usage.ts)

Consumption history for a credit meter, read from the provider's events API
— the events your server ingested when it spent credits. There is no local
usage ledger by design (`useCredits()` reads the balance cache; this reads
the history), so what renders here is exactly what the provider metered.

Degrades all the way down: signed-out visitors and backends without
`getUsageHistory` get an empty list rather than an error, and a failed load
lands in `error` instead of rejecting. Loads happen in the browser only;
changing `meter` or `limit` reloads from the first page.

#### Parameters

<table>
<thead>
  <tr>
    <th>
      Parameter
    </th>
    
    <th>
      Type
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        options?
      </code>
    </td>
    
    <td>
      <a href="#useusageoptions">
        <code>
          UseUsageOptions
        </code>
      </a>
    </td>
  </tr>
</tbody>
</table>

#### Returns

[`UseUsageReturn`](#useusagereturn)

#### Example

```vue
<script setup lang="ts">
const usage = useUsage({ meter: 'credits', limit: 20 })
</script>
<template>
  <p v-for="event in usage.events.value" :key="event.id">
    {{ event.timestamp }} — {{ event.name }} ({{ event.units }})
  </p>
</template>
```


## Sitemap

See the full [sitemap](https://nuxt-backend.dev/sitemap.md) for all pages.