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

# Entitlements

> Check feature access, usage limits, and margin state with nozle.can().

```python theme={null}
check = nozle.can("workspace_123", "api_calls")

if not check["allowed"]:
    raise PermissionError(check.get("reason", "Feature unavailable"))
```

## Metadata

Metadata values must be strings and are encoded as a JSON query parameter.

```python theme={null}
check = nozle.can(
    "workspace_123",
    "model_access",
    {"model": "example-large-model", "region": "us-east"},
)
```

## `CanResult`

| Field                     | Type              | Description                      |
| ------------------------- | ----------------- | -------------------------------- |
| `allowed`                 | `bool`            | Whether the request may proceed. |
| `reason`                  | `str`, optional   | Decision reason.                 |
| `used`                    | `int`             | Current usage.                   |
| `limit`                   | `int`, optional   | Configured limit.                |
| `remaining`               | `int`, optional   | Remaining allowance.             |
| `overage`                 | `bool`, optional  | Whether usage is in overage.     |
| `cost_per_use_cents`      | `int`             | Unit cost.                       |
| `revenue_per_use_cents`   | `int`             | Unit revenue.                    |
| `margin_per_use_cents`    | `int`             | Unit margin.                     |
| `margin_percent`          | `float`, optional | Margin percentage.               |
| `min_margin_percent`      | `float`, optional | Configured margin floor.         |
| `margin_level`            | `str`, optional   | Margin classification.           |
| `margin_enforcement_mode` | `str`, optional   | Enforcement behavior.            |
| `warning`                 | `str`, optional   | Non-blocking warning.            |

## FastAPI pattern

```python theme={null}
from fastapi import HTTPException

check = nozle.can(customer_id, "analytics")

if not check["allowed"]:
    raise HTTPException(
        status_code=429 if check.get("overage") else 403,
        detail={
            "reason": check.get("reason", "upgrade_required"),
            "used": check["used"],
            "limit": check.get("limit"),
            "remaining": check.get("remaining"),
        },
    )
```

Perform this check immediately before protected server work. React gates are not an authorization boundary. `can()` also does not reserve product credits; use `usage.track()` for atomic consumption.