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

# Get Usage

> Get current usage statistics for the authenticated user

## Endpoint

```
GET https://www.wiseyield.co/api/billing/usage
```

## Authentication

Requires a valid API key with `billing:read` scope.

## Response

Returns usage statistics object.

<ResponseField name="farmsCount" type="number">
  Number of active farms owned by user
</ResponseField>

<ResponseField name="aiRequestsThisMonth" type="number">
  Number of successful AI requests made this billing period (current month)
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X GET https://www.wiseyield.co/api/billing/usage \
    -H "Authorization: Bearer wy_YOUR_API_KEY"
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch(
    'https://www.wiseyield.co/api/billing/usage',
    {
      headers: {
        'Authorization': 'Bearer wy_YOUR_API_KEY'
      }
    }
  );

  const usage = await response.json();

  console.log(`Farms: ${usage.farmsCount}`);
  console.log(`AI Requests: ${usage.aiRequestsThisMonth}`);
  ```

  ```python Python theme={null}
  import requests

  response = requests.get(
      'https://www.wiseyield.co/api/billing/usage',
      headers={'Authorization': 'Bearer wy_YOUR_API_KEY'}
  )

  usage = response.json()

  print(f"Farms: {usage['farmsCount']}")
  print(f"AI Requests: {usage['aiRequestsThisMonth']}")
  ```
</RequestExample>

<ResponseExample>
  ```json 200 Success theme={null}
  {
    "farmsCount": 3,
    "aiRequestsThisMonth": 127
  }
  ```

  ```json 200 Success (No Usage) theme={null}
  {
    "farmsCount": 0,
    "aiRequestsThisMonth": 0
  }
  ```

  ```json 401 Unauthorized theme={null}
  {
    "error": "Unauthorized"
  }
  ```

  ```json 500 Internal Server Error theme={null}
  {
    "error": "Failed to fetch usage"
  }
  ```
</ResponseExample>

## Errors

<ResponseField name="401" type="error">
  Unauthorized - Missing or invalid API key
</ResponseField>

<ResponseField name="500" type="error">
  Internal Server Error - Failed to fetch usage statistics
</ResponseField>

## Usage Metrics Explained

### farmsCount

* **Definition**: Number of active farms user owns (not deleted)
* **Excludes**: Soft-deleted farms, farms user is member of but doesn't own
* **Updates**: Real-time (reflects current database state)

### aiRequestsThisMonth

* **Definition**: Count of successful AI requests made since billing period start
* **Billing Period**: Calendar month (resets on 1st of month)
* **Includes**: Only completed/successful requests
* **Excludes**: Failed requests, pending requests, requests from previous months

## Plan Limits

**Usage limits by plan tier**:

### Seed Plan (€22/month)

* **Farms**: 1 farm
* **AI Requests**: 50/month

### Sprout Plan (€49/month)

* **Farms**: 3 farms
* **AI Requests**: 200/month

### Harvest Plan (€89/month) ⭐

* **Farms**: 7 farms
* **AI Requests**: 500/month

### Grove Plan (€149/month)

* **Farms**: 15 farms
* **AI Requests**: 1,000/month

### Summit Plan (€299+/month)

* **Farms**: Unlimited
* **AI Requests**: Unlimited

## Use Cases

### Check Usage Against Limits

```javascript theme={null}
async function checkUsageLimits() {
  const [usageResponse, subscriptionResponse] = await Promise.all([
    fetch('/api/billing/usage', {
      headers: { 'Authorization': `Bearer ${apiKey}` }
    }),
    fetch('/api/billing/subscription', {
      headers: { 'Authorization': `Bearer ${apiKey}` }
    })
  ]);

  const usage = await usageResponse.json();
  const { subscription } = await subscriptionResponse.json();

  const plan = subscription?.plan || 'expired';

  const limits = {
    expired: { farms: 1, aiRequests: 50 },
    seed: { farms: 1, aiRequests: 50 },
    sprout: { farms: 3, aiRequests: 200 },
    harvest: { farms: 7, aiRequests: 500 },
    grove: { farms: 15, aiRequests: 1000 },
    summit: { farms: Infinity, aiRequests: Infinity }
  };

  const planLimits = limits[plan];

  return {
    farms: {
      used: usage.farmsCount,
      limit: planLimits.farms,
      percentage: (usage.farmsCount / planLimits.farms) * 100,
      remaining: planLimits.farms - usage.farmsCount
    },
    aiRequests: {
      used: usage.aiRequestsThisMonth,
      limit: planLimits.aiRequests,
      percentage: (usage.aiRequestsThisMonth / planLimits.aiRequests) * 100,
      remaining: planLimits.aiRequests - usage.aiRequestsThisMonth
    }
  };
}

// Usage
const limits = await checkUsageLimits();
if (limits.farms.percentage >= 80) {
  showUpgradePrompt('farms');
}
```

### Show Usage Dashboard

```javascript theme={null}
async function getUsageDashboard() {
  const response = await fetch('/api/billing/usage', {
    headers: { 'Authorization': `Bearer ${apiKey}` }
  });

  const usage = await response.json();

  return {
    farmsCount: usage.farmsCount,
    aiRequestsThisMonth: usage.aiRequestsThisMonth,
    aiRequestsRemaining: 500 - usage.aiRequestsThisMonth, // For harvest plan
    resetDate: new Date(new Date().getFullYear(), new Date().getMonth() + 1, 1)
  };
}
```

### Check Before Creating Resource

```javascript theme={null}
async function canCreateFarm() {
  const [usageResponse, subscriptionResponse] = await Promise.all([
    fetch('/api/billing/usage', {
      headers: { 'Authorization': `Bearer ${apiKey}` }
    }),
    fetch('/api/billing/subscription', {
      headers: { 'Authorization': `Bearer ${apiKey}` }
    })
  ]);

  const usage = await usageResponse.json();
  const { subscription } = await subscriptionResponse.json();

  const plan = subscription?.plan || 'expired';

  const farmLimits = {
    expired: 1,
    seed: 1,
    sprout: 3,
    harvest: 7,
    grove: 15,
    summit: Infinity
  };

  const limit = farmLimits[plan];
  const canCreate = usage.farmsCount < limit;

  if (!canCreate) {
    return {
      allowed: false,
      reason: `You've reached the ${plan} plan limit of ${limit} farm(s). Upgrade to create more farms.`,
      currentUsage: usage.farmsCount,
      limit
    };
  }

  return { allowed: true };
}

// Usage
const canCreate = await canCreateFarm();
if (!canCreate.allowed) {
  toast.error(canCreate.reason);
  showUpgradeDialog();
}
```

### Monitor AI Request Usage

```javascript theme={null}
async function checkAiRequestQuota() {
  const response = await fetch('/api/billing/usage', {
    headers: { 'Authorization': `Bearer ${apiKey}` }
  });

  const usage = await response.json();

  const limit = 500; // Harvest plan
  const used = usage.aiRequestsThisMonth;
  const percentage = (used / limit) * 100;

  return {
    used,
    limit,
    remaining: limit - used,
    percentage,
    willResetOn: new Date(new Date().getFullYear(), new Date().getMonth() + 1, 1),
    isNearLimit: percentage >= 80,
    isOverLimit: used >= limit
  };
}

// Usage
const quota = await checkAiRequestQuota();
if (quota.isNearLimit) {
  toast.warning(`You've used ${quota.percentage.toFixed(0)}% of your AI requests`);
}
```

## Best Practices

<Tip>
  **Check Before Actions**: Verify usage limits before allowing users to create farms or make AI requests.
</Tip>

<Tip>
  **Show Progress Bars**: Display usage as percentage of limit with visual progress bars.
</Tip>

<Tip>
  **Warn at 80%**: Alert users when they reach 80% of any limit to avoid surprises.
</Tip>

<Tip>
  **Display Reset Date**: Show when AI request counter resets (1st of next month).
</Tip>

<Warning>
  **Monthly Reset**: AI request count resets on 1st of each month, not on subscription anniversary.
</Warning>

<Warning>
  **Real-Time Data**: Usage numbers are real-time. Cache carefully to avoid stale data blocking actions.
</Warning>

<Warning>
  **Soft Limits**: Exceeding limits may trigger soft blocks. Always check before resource-intensive operations.
</Warning>

## Integration Examples

### Usage Dashboard Card

```javascript theme={null}
function UsageDashboardCard() {
  const [usage, setUsage] = useState(null);
  const [subscription, setSubscription] = useState(null);
  const [loading, setLoading] = useState(true);

  useEffect(() => {
    async function loadData() {
      try {
        const [usageRes, subRes] = await Promise.all([
          fetch('/api/billing/usage', {
            headers: { 'Authorization': `Bearer ${apiKey}` }
          }),
          fetch('/api/billing/subscription', {
            headers: { 'Authorization': `Bearer ${apiKey}` }
          })
        ]);

        const usageData = await usageRes.json();
        const { subscription } = await subRes.json();

        setUsage(usageData);
        setSubscription(subscription);
      } finally {
        setLoading(false);
      }
    }

    loadData();
  }, []);

  if (loading) return <div>Loading...</div>;

  const plan = subscription?.plan || 'expired';

  const limits = {
    expired: { farms: 1, aiRequests: 50 },
    seed: { farms: 1, aiRequests: 50 },
    sprout: { farms: 3, aiRequests: 200 },
    harvest: { farms: 7, aiRequests: 500 },
    grove: { farms: 15, aiRequests: 1000 },
    summit: { farms: Infinity, aiRequests: Infinity }
  };

  const planLimits = limits[plan];

  return (
    <div className="usage-card">
      <h3>Usage This Month</h3>

      <div className="usage-metric">
        <label>Farms</label>
        <ProgressBar
          value={usage.farmsCount}
          max={planLimits.farms}
          label={`${usage.farmsCount} / ${planLimits.farms === Infinity ? '∞' : planLimits.farms}`}
        />
      </div>

      <div className="usage-metric">
        <label>AI Requests</label>
        <ProgressBar
          value={usage.aiRequestsThisMonth}
          max={planLimits.aiRequests}
          label={`${usage.aiRequestsThisMonth} / ${planLimits.aiRequests === Infinity ? '∞' : planLimits.aiRequests}`}
        />

        <p className="reset-info">
          Resets: {new Date(new Date().getFullYear(), new Date().getMonth() + 1, 1).toLocaleDateString()}
        </p>
      </div>

      {(usage.farmsCount >= planLimits.farms || usage.aiRequestsThisMonth >= planLimits.aiRequests) && (
        <div className="upgrade-prompt">
          <p>You've reached your plan limits</p>
          <button onClick={() => router.push('/pricing')}>
            Upgrade Plan
          </button>
        </div>
      )}
    </div>
  );
}
```

### Usage Progress Bar

```javascript theme={null}
function UsageProgressBar({ used, limit, label }) {
  const percentage = limit === Infinity ? 0 : (used / limit) * 100;

  const getColor = () => {
    if (percentage >= 100) return 'red';
    if (percentage >= 80) return 'orange';
    return 'green';
  };

  return (
    <div className="progress-bar">
      <div className="progress-label">
        <span>{label}</span>
        <span>{used} / {limit === Infinity ? '∞' : limit}</span>
      </div>

      <div className="progress-track">
        <div
          className={`progress-fill bg-${getColor()}`}
          style={{ width: `${Math.min(percentage, 100)}%` }}
        />
      </div>

      <div className="progress-percentage">
        {limit === Infinity ? 'Unlimited' : `${percentage.toFixed(0)}%`}
      </div>
    </div>
  );
}
```

### Usage Guard Hook

```javascript theme={null}
function useUsageGuard(resourceType) {
  const [canCreate, setCanCreate] = useState(false);
  const [loading, setLoading] = useState(true);
  const [reason, setReason] = useState(null);

  useEffect(() => {
    async function checkUsage() {
      const [usageRes, subRes] = await Promise.all([
        fetch('/api/billing/usage', {
          headers: { 'Authorization': `Bearer ${apiKey}` }
        }),
        fetch('/api/billing/subscription', {
          headers: { 'Authorization': `Bearer ${apiKey}` }
        })
      ]);

      const usage = await usageRes.json();
      const { subscription } = await subRes.json();

      const plan = subscription?.plan || 'expired';

      const limits = {
        expired: { farms: 1, aiRequests: 50 },
        seed: { farms: 1, aiRequests: 50 },
        sprout: { farms: 3, aiRequests: 200 },
        harvest: { farms: 7, aiRequests: 500 },
        grove: { farms: 15, aiRequests: 1000 },
        summit: { farms: Infinity, aiRequests: Infinity }
      };

      const limit = resourceType === 'farm'
        ? limits[plan].farms
        : limits[plan].aiRequests;

      const current = resourceType === 'farm'
        ? usage.farmsCount
        : usage.aiRequestsThisMonth;

      const allowed = current < limit;

      setCanCreate(allowed);
      setReason(allowed ? null : `${plan} plan limit reached (${current}/${limit})`);
      setLoading(false);
    }

    checkUsage();
  }, [resourceType]);

  return { canCreate, loading, reason };
}

// Usage in component
function CreateFarmButton() {
  const { canCreate, loading, reason } = useUsageGuard('farm');

  if (loading) return <button disabled>Loading...</button>;

  return (
    <button
      onClick={handleCreateFarm}
      disabled={!canCreate}
      title={reason}
    >
      {canCreate ? 'Create Farm' : `Limit Reached - Upgrade to Create More`}
    </button>
  );
}
```

## Related Endpoints

* [Get Subscription](/api-reference/billing/get-subscription) - GET current subscription plan
* [Create Checkout Session](/api-reference/billing/create-checkout-session) - POST to upgrade plan
* [Create Portal Session](/api-reference/billing/create-portal-session) - POST to manage subscription
* [Get Invoices](/api-reference/billing/get-invoices) - GET payment history