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

# Usage

> Track current UTC-date API usage metrics and view daily usage history.

## Overview

The `usage` client provides daily API usage metrics. `current()` returns the current UTC date's counters; `history()` returns earlier daily counters.

Access the usage client via `client.usage`.

## Current

Get API usage metrics for the current UTC date.

```python theme={null}
from grantex import Grantex

with Grantex(api_key="gx_live_...") as client:
    usage = client.usage.current()

    print(f"Developer: {usage.developer_id}")
    print(f"Date: {usage.period}")
    print(f"Token exchanges: {usage.token_exchanges}")
    print(f"Authorizations: {usage.authorizations}")
    print(f"Verifications: {usage.verifications}")
    print(f"Total requests: {usage.total_requests}")
```

### UsageMetrics

| Field | Type | Description |
| - | - | - |
| `developer_id` | `str` | The developer organization ID. |
| `period` | `str` | Current UTC date in `YYYY-MM-DD` form; the wire field name is retained for compatibility. |
| `token_exchanges` | `int` | Number of token exchange operations on this UTC date. |
| `authorizations` | `int` | Number of authorization requests on this UTC date. |
| `verifications` | `int` | Number of token verifications on this UTC date. |
| `total_requests` | `int` | Total API requests across all endpoints on this UTC date. |

## History

Retrieve historical usage data for the specified number of days, broken down by day.

```python theme={null}
from grantex import Grantex

with Grantex(api_key="gx_live_...") as client:
    history = client.usage.history(days=7)

    for entry in history.entries:
        print(f"{entry.date}: {entry.total_requests} requests")
        print(f"  Exchanges: {entry.token_exchanges}")
        print(f"  Authorizations: {entry.authorizations}")
        print(f"  Verifications: {entry.verifications}")
```

### Parameters

| Parameter | Type | Required | Description |
| - | - | - | - |
| `days` | `int` | Yes | Number of days of history to retrieve (e.g., 7, 30, 90). |

### UsageHistory

| Field | Type | Description |
| - | - | - |
| `entries` | `list[UsageEntry]` | Daily usage entries, ordered newest to oldest. |

### UsageEntry

| Field | Type | Description |
| - | - | - |
| `date` | `str` | The date in `YYYY-MM-DD` format. |
| `token_exchanges` | `int` | Number of token exchange operations on this day. |
| `authorizations` | `int` | Number of authorization requests on this day. |
| `verifications` | `int` | Number of token verifications on this day. |
| `total_requests` | `int` | Total API requests on this day. |

## Example: Usage Dashboard

```python theme={null}
from grantex import Grantex

with Grantex(api_key="gx_live_...") as client:
    # Check current UTC-date usage
    current = client.usage.current()
    print(f"Date: {current.period}")
    print(f"Total requests: {current.total_requests}")
    print(f"  Authorizations: {current.authorizations}")
    print(f"  Token exchanges: {current.token_exchanges}")
    print(f"  Verifications: {current.verifications}")

    # Get last 30 days of usage
    history = client.usage.history(days=30)
    total_month = sum(e.total_requests for e in history.entries)
    print(f"\nLast 30 days: {total_month} total requests")

    # Find peak usage day
    peak = max(history.entries, key=lambda e: e.total_requests)
    print(f"Peak day: {peak.date} ({peak.total_requests} requests)")
```

## Ownership

Grantex is owned by Orchestrum Technologies LLP. Inventor and owner: Sanjeev Kumar. Ownership contact: [sanjeev@orchestrum.in](mailto:sanjeev@orchestrum.in) or [mishra.sanjeev@gmail.com](mailto:mishra.sanjeev@gmail.com).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.