Processing Unit Definition¶

Plot Size Limit¶

Processing Units in Epoch's API is calculated on the basis of 20 hectares plots. Plots inferior to 20 hectares are still billed a single processing unit.

For plots superior to 20 hectares, the number of processing units incurred is the multiple of 20 hectares, rounded up. For instance, a 81 hectare plot will be billed as 5 processing units (5 * 20 = 100 hectares).

Core operations have a limit of 100 000 hectares. Although this is the upper size limit, it is recommended to consider the cost implication of running such a large plot using core API endpoints.

For very large plots (from 100 hectares up to 1 Million hectares), it is recommended to use the batch API endpoints, which are intended for large plot volumes (hundreds to tens of thousands) and/or large plots (100 hectares and above).

Plan Limits and Quotas¶

Epoch's API implements several types of limits to ensure fair usage and optimal performance for all users. These limits are defined in your subscription plan and are enforced across all API operations.

Limit Types¶

1. API Calls Per Month (`numAPICallsPerMonth`)¶

What it limits: The total number of API requests you can make per month
How it's counted: Each API endpoint call counts as one request
Example: If your limit is 1000 calls/month, you can make 1000 requests to any combination of endpoints
Reset period: Monthly (resets on the first day of each month)

2. Plot Count (`numPlots`)¶

What it limits: The total number of plots you can process per period
How it's counted: Each plot processed through any API endpoint counts toward this limit
Example: If your limit is 100 plots/month, you can process 100 individual plots
Reset period: Based on your plan's check period (monthly or yearly)

3. Area Count (`numArea`)¶

What it limits: The total area (in hectares) you can process per period
How it's counted: Sum of all plot areas processed
Example: If your limit is 1000 hectares/month, you can process plots totaling 1000 hectares
Reset period: Based on your plan's check period (monthly or yearly)

4. Supply Shed Count (`numSupplySheds`)¶

What it limits: The number of supply sheds you can create per period
How it's counted: Each supply shed creation counts as one
Example: If your limit is 10 supply sheds/month, you can create 10 supply sheds
Reset period: Based on your plan's check period (monthly or yearly)

5. Maximum Area Per Plot (`maxAreaPerPlot`)¶

What it limits: The maximum average area per plot you can process
How it's calculated: Total area processed ÷ Number of plots processed
Example: If your limit is 50 hectares/plot, your average plot size cannot exceed 50 hectares
Purpose: Prevents abuse by processing very large plots that could impact system performance

Plan Periods¶

Plans can have different check periods that determine when limits reset:

Monthly: Limits reset on the first day of each month
Yearly: Limits reset on a rolling 12-month basis from your first usage

Checking Your Usage¶

You can monitor your current usage and limits using the following endpoints:

/check_user_plan: Get detailed information about your current plan limits and usage
/user_consumption: View your consumption metrics for the current period

Example Response from `/check_user_plan`¶

{
  "user_id": "user@example.com",
  "plan_type": "free",
  "within_limits": true,
  "plots": {
    "limit": 100,
    "used": 25,
    "remaining": 75,
    "percentage_used": 25.0
  },
  "api_calls": {
    "limit": 1000,
    "used": 150,
    "remaining": 850,
    "percentage_used": 15.0
  },
  "supply_sheds": {
    "limit": 3,
    "used": 1,
    "remaining": 2,
    "percentage_used": 33.33
  },
  "area": {
    "limit": 1000,
    "used": 500.5,
    "remaining": 499.5,
    "percentage_used": 50.05
  },
  "max_area_per_plot": {
    "limit": 50,
    "used": 20.02,
    "remaining": 29.98,
    "percentage_used": 40.04
  },
  "period_start": "2024-01-01",
  "period_end": "2024-01-31",
  "warnings": []
}

What Happens When Limits Are Exceeded¶

When any limit is exceeded, the API will return:

HTTP 403 Forbidden status code
A detailed error message indicating which limit was exceeded
Information about your current usage vs. limits

Best Practices¶

Monitor Usage Regularly: Use the /check_user_plan endpoint to track your consumption
Plan Your Operations: Consider your limits when planning large batch operations
Use Batch Endpoints: For large datasets, use batch endpoints which are optimized for high-volume processing
Contact Support: If you need higher limits, contact our support team for custom quota adjustments

Free Plan Default Limits¶

The free plan includes the following default limits: - API Calls: 100 per month - Plots: 100 per month - Area: 1,000 hectares per month - Supply Sheds: 3 per month - Max Area Per Plot: 50 hectares

These limits are designed to allow users to explore the API while preventing abuse. For production use or higher limits, consider upgrading to a paid plan.