Skip to main content
GET

Endpoint

Authentication

Requires a valid API key with billing:read scope.

Response

Returns usage statistics object.
number
Number of active farms owned by user
number
Number of successful AI requests made this billing period (current month)

Errors

error
Unauthorized - Missing or invalid API key
error
Internal Server Error - Failed to fetch usage statistics

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

Show Usage Dashboard

Check Before Creating Resource

Monitor AI Request Usage

Best Practices

Check Before Actions: Verify usage limits before allowing users to create farms or make AI requests.
Show Progress Bars: Display usage as percentage of limit with visual progress bars.
Warn at 80%: Alert users when they reach 80% of any limit to avoid surprises.
Display Reset Date: Show when AI request counter resets (1st of next month).
Monthly Reset: AI request count resets on 1st of each month, not on subscription anniversary.
Real-Time Data: Usage numbers are real-time. Cache carefully to avoid stale data blocking actions.
Soft Limits: Exceeding limits may trigger soft blocks. Always check before resource-intensive operations.

Integration Examples

Usage Dashboard Card

Usage Progress Bar

Usage Guard Hook