## Events list

You can monitor every event flowing into Lago from the UI. This is your primary tool for verifying that your integration is working and debugging any issues.

1. **Open the events list**  
   Go to the **Developers** section in the sidebar, then click the **Events** tab.

2. **Browse ingested events**  
   The UI shows the latest 20 events by default. Scroll down to load more.

3. **Inspect a specific event**  
   Click any event to see its details:
   - **Time:** timestamp of the received event
   - **Customer ID:** the ID of your customer
   - **Billable metric code:** code of the billable metric linked to the event
   - **Billable metric name:** name of the billable metric linked to the event
   - **Transaction ID:** unique `transaction_id` used as the idempotency key
   - **IP Address:** IP address of the event sender
   - **Client API:** Lago Client API used to send the event
   - **Event payload:** the full JSON arguments sent in the request

If an event is not shown in the UI, it has **not** been ingested.

### Possible warnings

Some events can be ingested but trigger unexpected behavior. Lago displays two possible warnings in the UI:

1. The event `code` is **not related to an existing billable metric**
2. The billable metric’s **property used for the aggregation is not sent** through this event

* * *

## Retrieve current usage

The [current usage endpoint](https://getlago.com/docs/api-reference/customer-usage/get-current) retrieves real-time usage data for the current open billing period. Because this billing period is still ongoing, invoice details are subject to change as new usage continues to accrue. Whether it’s fetched from the UI or the API, the response includes:

1. Aggregated usage data for the current period: Total units consumed and total customers’ cost (so far)
2. Detailed breakdowns per metric: Units and amounts by metric and optional sub-breakdowns by filters or groupings (e.g., per project, environment, or AI models)

Note: Since the billing period is not yet finalized, the retrieved data should be treated as provisional. Final invoice values may differ.

Notice that if the events were sent with a timestamp in the future, they are taken into account in current usage. Yet, if you terminate the subscription before the timestamp of this event, it will be ignored in the termination invoice.

### Retrieving current usage

```
LAGO_URL="https://api.getlago.com"
API_KEY="__YOUR_API_KEY__"
EXTERNAL_CUSTOMER_ID="__EXTERNAL_CUSTOMER_ID__"
EXTERNAL_SUBSCRIPTION_ID="__EXTERNAL_SUBSCRIPTION_ID__"

curl --location --request GET "$LAGO_URL/api/v1/customers/$EXTERNAL_CUSTOMER_ID/current_usage?external_subscription_id=$EXTERNAL_SUBSCRIPTION_ID" \
--header "Authorization: Bearer $API_KEY" \
--header 'Content-Type: application/json'
```

## Retrieve projected usage

Another endpoint provides an estimate of usage and billing amounts projected through the end of the current billing period. It uses current consumption trends and billing configuration to forecast the likely totals at period close. Projected usage is listed under the [projected usage endpoint](https://getlago.com/docs/api-reference/customer-usage/get-projected). Whether it’s fetched from the UI or the API, the response includes:

1. Projected total usage units and estimated billing amount for the full billing period
2. Per-metric projections, including: Forecasted units and amounts for each billable metric and projections broken down by optional sub-filters or groups (e.g., per project, environment, or AI models)

Note: Recurring metrics, such as Seats, typically remain stable over time, unlike metered metrics which fluctuate. Therefore, the projected usage for a recurring metric is assumed to be equal to its current usage.

### Retrieving projected usage

curl --location --request GET "$LAGO_URL/api/v1/customers/$EXTERNAL_CUSTOMER_ID/projected_usage?external_subscription_id=$EXTERNAL_SUBSCRIPTION_ID" \
--header "Authorization: Bearer $API_KEY" \
--header 'Content-Type: application/json'
```

## Retrieve past usage

The [past usage endpoint](https://getlago.com/docs/api-reference/customer-usage/get-past) allows you to retrieve customer usage data for closed billing periods. Once a billing period has ended and is marked as closed, the associated usage data becomes final and immutable, ensuring consistency in billing and reporting. Modifying the price of a metric, or even deleting a metric, has no effect on past usage or previously issued invoices. Once a billing period is closed and its associated invoice is finalized, the past usage quantities, pricing, and resulting fees are locked.

### Retrieve past usage

curl --location --request GET "$LAGO_URL/api/v1/customers/$EXTERNAL_CUSTOMER_ID/past_usage?external_subscription_id=$EXTERNAL_SUBSCRIPTION_ID" \
--header "Authorization: Bearer $API_KEY" \
--header 'Content-Type: application/json'
```