# 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 by not specifying the indicator ID. In this case consumption is not recorded. Other endpoints (authentication, search, etc.) do not count toward your usage limits.

#### What Counts as Consumption

:white\_check\_mark: **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

:x: **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:

```http
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

```bash
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.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.api.ecoinvent.org/getting-started/usage-tracking-and-consumption.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.