Usage Tracking & Consumption

Understanding Your API Consumption

Your ecoinvent API usage is measured based on three key metrics that align with your license agreement:

• Number of unique users accessing the API

• Number of unique datasets requested

• Number of unique indicators requested

Important: Consumption is only recorded when you make successful calls to the /datasets endpoint and get scores. It is possible to use /datasets while fetching no scores, in this case consumption is not recorded. Other endpoints (authentication, search, etc.) do not count toward your usage limits.

What Counts as Consumption

✅ Counts toward limits:

• Each unique user making requests (identified by X-User-ID header)

• Each unique dataset accessed by any user during your license period

• Each unique indicator requested from any dataset by any user during your license period

❌ Does not count toward limits:

• Failed API requests (4xx or 5xx responses)

• Calls to other endpoints (search, authentication, etc.)

• Multiple calls to the same dataset - you're only charged once per unique dataset

• Multiple requests for the same indicator - you're only charged once per unique indicator

Example: If User A requests Dataset 123 (containing 5 indicators) multiple times, this counts as: 1 unique user + 1 unique dataset + 5 unique indicators toward your consumption limits, regardless of how many times the calls are made.

Setting Up Usage Tracking

To enable accurate usage tracking and ensure you receive detailed consumption reports, you must include identification headers with your API requests.

Required Headers

When calling the /datasets endpoint, include these headers:

X-User-ID: your_user_unique_identifier
X-Organization-ID: your_organization_unique_identifier (Optional)

Header Guidelines

• Use consistent identifiers: Choose IDs that remain the same across all requests for the same user/organization

• Make them meaningful: Use identifiers that help you track usage internally (e.g., employee IDs, department codes)

• Keep them simple: Alphanumeric strings work best

• Both headers are strongly recommended: While organization ID is optional, including both gives you better reporting granularity

Example Request

curl -X GET "https://api.ecoinvent.org/datasets/12345?indicators=964,897,962" \
  -H "Authorization: Bearer your_access_token" \
  -H "X-User-ID: employee_001" \
  -H "X-Organization-ID: sustainability_team" \
  -H "Content-Type: application/json"

Usage Reports & Monitoring

What Reports You'll Receive

You'll have access to comprehensive usage reports through your account dashboard, including:

Consolidated Summary

• Total users, datasets, and indicators consumed during the reporting period

• Usage compared to your license limits

• Validity period covered

User Detail Summary

• Breakdown by individual user and organization

• Datasets and indicators accessed per user

API Consumption Log

• Detailed record of every consumption event

• Timestamps, user IDs, dataset IDs, and indicator IDs

• Complete audit trail for your records

Monitoring Your Usage

⚠️ Beta Notice: During the beta period, the API does not automatically prevent you from exceeding your license limits. Please monitor your consumption to avoid unexpected charges.

Recommended practices:

• Review your usage reports regularly

• Set internal alerts when approaching limits

Accessing Reports

Usage reports are available through your account dashboard (https://accounts.ecoinvent.org/api) and are updated in real-time as consumption occurs. Reports cover the validity period of your current license agreement.

---

Questions? Contact your account manager if you need clarification on your specific license limits or usage tracking requirements.