User Consumption¶

Overview¶

The user_consumption endpoint allows you to retrieve consumption metrics for your API usage. It tracks metrics including API calls, plot counts, supply shed counts, and processed area within a given period.

Endpoint¶

URL: /user_consumption
Method: GET
Authentication: Required (Bearer token)
Content-Type: application/json

GET /check_user_plan: plan limits + “within limits” status (documented at the bottom of this page)

Query Parameters¶

Parameter	Type	Required	Default	Description
`start_date`	string	No	Auto-determined	Start date in `YYYY-MM-DD` format
`end_date`	string	No	Auto-determined	End date in `YYYY-MM-DD` format
`client_id`	string	No	None	Filter consumption by specific client ID
`legacy`	boolean	No	false	Use legacy data queries instead of real-time tracking

Period Resolution Logic¶

When start_date and end_date are not provided, the endpoint automatically determines the appropriate period based on your plan settings:

Explicit Dates: If both start_date and end_date are provided, they are used as-is
Plan-Based Period: If planDetails.checkPeriod is set:
"monthly": First day of current month to today
"yearly": One year ago to today (rolling window)
Plan Type Fallback: If checkPeriod is not set and planType is "free": Uses monthly period
Default Fallback: If no plan information is available: Uses yearly period

Authentication¶

This endpoint supports two authentication methods:

Email/Password Authentication: Standard user authentication
Client Credentials Authentication: API client authentication with embedded client_id

The endpoint automatically detects your authentication method and organizes consumption data accordingly. For email/password authentication, the endpoint looks up the user's email address and uses it as the key in the response instead of the internal user ID.

Response¶

The endpoint always returns a consistent structure with the following components:

Base response format¶

{
  "user_ids": {
    "user@example.com": {
      "call_count": 150,
      "plot_count": 75,
      "supply_shed_count": 10,
      "area_count": 500.5
    }
  },
  "client_ids": {
    "client_123": {
      "call_count": 300,
      "plot_count": 150,
      "supply_shed_count": 20,
      "area_count": 1000.0
    }
  },
  "total": {
    "call_count": 450,
    "plot_count": 225,
    "supply_shed_count": 30,
    "area_count": 1500.5
  }
}

Response fields¶

Field	Type	Description
`user_ids`	object	Consumption metrics for email/password authenticated requests (keys are user email addresses)
`client_ids`	object	Consumption metrics for client credentials authenticated requests (keys are client IDs)
`total`	object	Aggregated totals across all authentication methods

Metric definitions¶

Metric	Description
`call_count`	Total number of API calls made within the date range
`plot_count`	Total number of plot rows across all `_plot` tables
`supply_shed_count`	Number of `_supply_shed` tables created
`area_count`	Total geometric area in hectares across all plots

Usage examples¶

Basic usage (plan-based period)¶

curl -X GET "https://epoch-sco2-api.com/user_consumption" \
  -H "Authorization: Bearer YOUR_TOKEN"

Note: Period is automatically determined based on your plan settings

Response:

{
  "user_ids": {
    "user@example.com": {
      "call_count": 150,
      "plot_count": 75,
      "supply_shed_count": 10,
      "area_count": 500.5
    }
  },
  "client_ids": {
    "client_123": {
      "call_count": 300,
      "plot_count": 150,
      "supply_shed_count": 20,
      "area_count": 1000.0
    }
  },
  "total": {
    "call_count": 450,
    "plot_count": 225,
    "supply_shed_count": 30,
    "area_count": 1500.5
  }
}

Filter by date range¶

curl -X GET "https://epoch-sco2-api.com/user_consumption?start_date=2024-01-01&end_date=2024-01-31" \
  -H "Authorization: Bearer YOUR_TOKEN"

Filter by client ID¶

curl -X GET "https://epoch-sco2-api.com/user_consumption?client_id=client_123" \
  -H "Authorization: Bearer YOUR_TOKEN"

Response (when client_id is specified):

{
  "client_ids": {
    "client_123": {
      "call_count": 300,
      "plot_count": 150,
      "supply_shed_count": 20,
      "area_count": 1000.0
    }
  },
  "total": {
    "call_count": 450,
    "plot_count": 225,
    "supply_shed_count": 30,
    "area_count": 1500.5
  }
}

Non-existent Client ID¶

curl -X GET "https://epoch-sco2-api.com/user_consumption?client_id=non_existent_client" \
  -H "Authorization: Bearer YOUR_TOKEN"

Response:

{
  "client_ids": {
    "non_existent_client": {
      "call_count": 0,
      "plot_count": 0,
      "supply_shed_count": 0,
      "area_count": 0.0
    }
  },
  "total": {
    "call_count": 450,
    "plot_count": 225,
    "supply_shed_count": 30,
    "area_count": 1500.5
  }
}

Legacy mode¶

curl -X GET "https://epoch-sco2-api.com/user_consumption?legacy=true" \
  -H "Authorization: Bearer YOUR_TOKEN"

Response (legacy mode always returns aggregate):

{
  "total": {
    "call_count": 450,
    "plot_count": 225,
    "supply_shed_count": 30,
    "area_count": 1500.5
  }
}

Python Examples¶

import requests

# API configuration
API_BASE_URL = "https://epoch-sco2-api.com"
TOKEN = "your_bearer_token_here"

headers = {
    "Authorization": f"Bearer {TOKEN}",
    "Content-Type": "application/json"
}

# Example 1: Get all consumption data (default: last year to today)
response = requests.get(f"{API_BASE_URL}/user_consumption", headers=headers)
data = response.json()

# Example 2: Get consumption for specific date range
params = {
    "start_date": "2024-01-01",
    "end_date": "2024-01-31"
}
response = requests.get(f"{API_BASE_URL}/user_consumption", headers=headers, params=params)
data = response.json()

# Example 3: Get consumption for specific client
params = {"client_id": "client_123"}
response = requests.get(f"{API_BASE_URL}/user_consumption", headers=headers, params=params)
data = response.json()

# Example 4: Get consumption for specific client and date range
params = {
    "client_id": "client_123",
    "start_date": "2024-01-01",
    "end_date": "2024-01-31"
}
response = requests.get(f"{API_BASE_URL}/user_consumption", headers=headers, params=params)
data = response.json()

Data Sources¶

Modern Mode (Default)¶

Primary: Real-time usage tracking
Fallback: Historical data queries if real-time data is incomplete
Features: Real-time aggregation, client-specific tracking

Legacy Mode¶

Source: Historical data queries only
Limitations: No client-specific breakdown, aggregate totals only
Use Case: Backward compatibility for older implementations

Error Handling¶

HTTP Status	Description
`200`	Success - Consumption data retrieved
`401`	Unauthorized - Invalid or missing authentication token
`404`	Not Found - User data plan could not be retrieved
`422`	Validation Error - Invalid date format or parameters

Best Practices¶

Date Ranges: Use reasonable date ranges to avoid performance issues
Client Filtering: Use client_id parameter when you need specific client data
Monitoring: Regularly check consumption to stay within plan limits
Authentication: Use appropriate authentication method for your use case

Quick Reference¶

Common Use Cases¶

Use Case	Parameters	Response Focus
Check total usage	None	`total` field
Monitor specific client	`client_id=client_123`	`client_ids` field
Historical analysis	`start_date=2024-01-01&end_date=2024-01-31`	All fields
Legacy compatibility	`legacy=true`	`total` field only

Response Field Access¶

// Get total API calls
const totalUsage = response.total;

// Get specific client usage (direct access by client_id)
const clientUsage = response.client_ids['client_123'];

// Get user-specific usage (direct access by user_id)
const userUsage = response.user_ids['user@example.com'];

# Get total API calls
total_usage = response['total']

# Get specific client usage (direct access by client_id)
client_usage = response['client_ids']['client_123']

# Get user-specific usage (direct access by user_id)
user_usage = response['user_ids']['user@example.com']

---

# Check User Plan Endpoint

## Overview

The `check_user_plan` endpoint allows you to check your current plan consumption and remaining quota. This endpoint provides detailed information about your plan limits, current usage, and whether you're within your plan boundaries.

## Endpoint Details

- **URL**: `/check_user_plan`
- **Method**: `GET`
- **Authentication**: Required (Bearer token)
- **Content-Type**: `application/json`

## Query Parameters

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `start_date` | string | No | Auto-determined | Start date in `YYYY-MM-DD` format |
| `end_date` | string | No | Auto-determined | End date in `YYYY-MM-DD` format |
| `client_id` | string | No | None | Filter consumption by specific client ID |
| `legacy` | boolean | No | false | Use legacy data queries instead of real-time tracking |

## Period Resolution Logic

When `start_date` and `end_date` are not provided, the endpoint automatically determines the appropriate period based on your plan settings:

1. **Explicit Dates**: If both `start_date` and `end_date` are provided, they are used as-is
2. **Plan-Based Period**: If `planDetails.checkPeriod` is set:
   - `"monthly"`: First day of current month to today
   - `"yearly"`: One year ago to today (rolling window)
3. **Plan Type Fallback**: If `checkPeriod` is not set and `planType` is `"free"`: Uses monthly period
4. **Default Fallback**: If no plan information is available: Uses yearly period

## Response Structure

The endpoint returns detailed plan information with consumption metrics and limits:

```json
{
  "user_id": "user@example.com",
  "plan_name": "Professional",
  "within_limits": true,
  "plots": {
    "limit": 1000,
    "used": 750,
    "remaining": 250,
    "percentage_used": 75.0
  },
  "api_calls": {
    "limit": 10000,
    "used": 8500,
    "remaining": 1500,
    "percentage_used": 85.0
  },
  "supply_sheds": {
    "limit": 50,
    "used": 30,
    "remaining": 20,
    "percentage_used": 60.0
  },
  "area": {
    "limit": 10000,
    "used": 7500,
    "remaining": 2500,
    "percentage_used": 75.0
  },
  "max_area_per_plot": {
    "limit": 100,
    "used": 85,
    "remaining": 15,
    "percentage_used": 85.0
  },
  "period_start": "2024-01-01",
  "period_end": "2024-01-31",
  "warnings": [
    "API calls at 85% - consider upgrading plan"
  ]
}

Response Fields¶

Field	Type	Description
`user_id`	string	User's email address
`plan_name`	string	Name of the user's current plan
`within_limits`	boolean	Whether the user is within their plan limits
`plots`	object	Plot count limits and usage
`api_calls`	object	API call limits and usage
`supply_sheds`	object	Supply shed count limits and usage
`area`	object	Area limits and usage (in hectares)
`max_area_per_plot`	object	Maximum area per plot limits and usage
`period_start`	string	Start date of the consumption period
`period_end`	string	End date of the consumption period
`warnings`	array	List of warnings about approaching limits

Limit Information Structure¶

Each limit field (plots, api_calls, etc.) contains:

Field	Type	Description
`limit`	integer	Maximum allowed value for this metric
`used`	integer/float	Current usage value
`remaining`	integer/float	Remaining quota
`percentage_used`	float	Percentage of limit used (0-100)

Usage Examples¶

Basic Usage (Plan-Based Period)¶

curl -X GET "https://epoch-sco2-api.com/check_user_plan" \
  -H "Authorization: Bearer YOUR_TOKEN"

Note: Period is automatically determined based on your plan settings

Check Specific Date Range¶

curl -X GET "https://epoch-sco2-api.com/check_user_plan?start_date=2024-01-01&end_date=2024-01-31" \
  -H "Authorization: Bearer YOUR_TOKEN"

Check Specific Client¶

curl -X GET "https://epoch-sco2-api.com/check_user_plan?client_id=client_123" \
  -H "Authorization: Bearer YOUR_TOKEN"

Python Examples¶

import requests

# API configuration
API_BASE_URL = "https://epoch-sco2-api.com"
TOKEN = "your_bearer_token_here"

headers = {
    "Authorization": f"Bearer {TOKEN}",
    "Content-Type": "application/json"
}

# Example 1: Check current month plan status
response = requests.get(f"{API_BASE_URL}/check_user_plan", headers=headers)
data = response.json()

# Example 2: Check specific date range
params = {
    "start_date": "2024-01-01",
    "end_date": "2024-01-31"
}
response = requests.get(f"{API_BASE_URL}/check_user_plan", headers=headers, params=params)
data = response.json()

# Example 3: Check specific client
params = {"client_id": "client_123"}
response = requests.get(f"{API_BASE_URL}/check_user_plan", headers=headers, params=params)
data = response.json()

# Check if within limits
if data['within_limits']:
    print("✅ Within plan limits")
else:
    print("❌ Exceeded plan limits")
    print("Warnings:", data['warnings'])

# Check specific metrics
api_usage = data['api_calls']
print(f"API calls: {api_usage['used']}/{api_usage['limit']} ({api_usage['percentage_used']}%)")

Plan Limits¶

The endpoint checks against the following plan limits:

Metric	Description	Plan Types
`plots`	Number of plot rows across all tables	All plans
`api_calls`	Total API calls made	All plans
`supply_sheds`	Number of supply shed tables created	All plans
`area`	Total area processed in hectares	All plans
`max_area_per_plot`	Maximum area allowed per individual plot	All plans

Warnings and Alerts¶

The endpoint provides warnings when:

75%+ usage: "approaching limit" warning
90%+ usage: "consider upgrading plan" warning
100%+ usage: "limit exceeded" warning

Error Handling¶

HTTP Status	Description
`200`	Success - Plan information retrieved
`400`	Bad Request - Plan limits exceeded
`401`	Unauthorized - Invalid or missing authentication token
`404`	Not Found - User data plan could not be retrieved
`422`	Validation Error - Invalid date format or parameters

Best Practices¶

Regular Monitoring: Check plan status regularly to avoid hitting limits
Proactive Upgrades: Monitor warnings and upgrade plans before hitting limits
Client-Specific Tracking: Use client_id parameter to track specific client usage
Date Range Analysis: Use custom date ranges for historical analysis

Quick Reference¶

Common Use Cases¶

Use Case	Parameters	Response Focus
Check current status	None	`within_limits` and `warnings`
Monitor specific client	`client_id=client_123`	Client-specific limits
Historical analysis	`start_date=2024-01-01&end_date=2024-01-31`	Historical consumption
Plan upgrade decision	Check `percentage_used` values	All limit fields

Response Field Access¶

// Check if within limits
const withinLimits = response.within_limits;

// Get plan name
const planName = response.plan_name;

// Check API call usage
const apiUsage = response.api_calls;
const apiPercentage = apiUsage.percentage_used;

// Get warnings
const warnings = response.warnings;

# Check if within limits
within_limits = response['within_limits']

# Get plan name
plan_name = response['plan_name']

# Check API call usage
api_usage = response['api_calls']
api_percentage = api_usage['percentage_used']

# Get warnings
warnings = response['warnings']

User Consumption¶

Overview¶

Endpoint¶

Related endpoint¶

Query Parameters¶

Period Resolution Logic¶

Authentication¶

Response¶

Base response format¶

Response fields¶

Metric definitions¶

Usage examples¶

Basic usage (plan-based period)¶

Filter by date range¶

Filter by client ID¶

Non-existent Client ID¶

Legacy mode¶

Python Examples¶

Data Sources¶

Modern Mode (Default)¶

Legacy Mode¶

Error Handling¶

Best Practices¶

Quick Reference¶

Common Use Cases¶

Response Field Access¶

Response Fields¶

Limit Information Structure¶

Usage Examples¶

Basic Usage (Plan-Based Period)¶

Check Specific Date Range¶

Check Specific Client¶

Python Examples¶

Plan Limits¶

Warnings and Alerts¶

Error Handling¶

Best Practices¶

Quick Reference¶

Common Use Cases¶

Response Field Access¶