> ## Documentation Index
> Fetch the complete documentation index at: https://docs.flexprice.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Usage by Properties

> Group and filter a customer's usage and cost by event properties such as region, model or instance in the Customer Portal or through its analytics API

A usage chart that only splits by feature cannot answer the questions customers actually ask: which region is driving the bill, which model costs the most, which instance spiked last week. With usage properties turned on, customers can group and filter usage by event property on the hosted portal's **Usage** tab. The same controls are available through the portal analytics API for a front end you build.

The feature is off by default. You turn it on per environment and choose which properties customers can see.

## Using property controls

On the **Usage** tab, use the filter bar to narrow usage by feature or property value. In **Usage breakdown**, use **Group by** to choose a property. A front end you build can use the corresponding request fields:

| Control | What it does | Request field |
| - | - | - |
| Feature filter | Narrows the view to one or more features | `feature_ids` |
| **Group by** | Groups the breakdown by one property, for example **By region** | `group_by` |
| Property filter | Keeps only usage whose property matches the chosen values, for example `cloud_provider` is `aws` | `property_filters` |

To drill down, combine the two: filter `region` to `us-east-1` and group by `instance_id`. Grouping is available when the server returns visible property keys for the customer and date range. A property's filter appears when values are available for it.

* **The breakdown groups property values by cost**, highest first. Expand a group to see its features, usage and cost.
* **Usage without the property** appears under **No value**.
* **Grouping changes the breakdown, not the trend chart.** The chart and metric cards respect the active feature and property filters. Cost and margin cards appear only when enabled in the [portal configuration](https://docs.flexprice.io/docs/customers/customer-portal/configuration.md#what-the-portal-applies).

## Turning it on

In the dashboard, open **Settings** → **Customer experience** → **Portal**. Keep the Usage section visible, then under **Usage properties**, turn on **Customers can group their usage by event property**. Optionally enter comma-separated keys in **Only these keys** and **Never these keys**, then click **Save changes**. Reload the customer's portal to use the controls.

Alternatively, write `analytics_config` into the `customer_portal_config` setting through the settings API. Both methods configure the hosted portal and its analytics endpoints:

```bash theme={null}
curl --request PUT \
  --url https://api.cloud.flexprice.io/v1/settings/customer_portal_config \
  --header 'x-api-key: <your_api_key>' \
  --header 'Content-Type: application/json' \
  --data '{
    "value": {
      "analytics_config": {
        "usage_properties": {
          "enabled": true,
          "allowed_keys": ["region", "model"],
          "hidden_keys": ["user_email"]
        }
      }
    }
  }'
```

| Field | Effect |
| - | - |
| `enabled` | Turns the feature on. It stays off until you set it to `true` |
| `allowed_keys` | Customers see only these properties. Leave empty to show all of them |
| `hidden_keys` | Customers never see these properties |

The write replaces `analytics_config` as a whole and leaves the rest of the setting, such as your sections and theme, as it is. Send all three fields every time, because a field you leave out is cleared.

Settings writes require Super Admin. Through the API, use a Super Admin user's API key; a service account key is refused. The portal panel edits the same setting, and **Reset to defaults** deletes it.

To find property names for the lists, call `POST /v1/meter-usage/properties` with your API key. See [API](#api).

> [!NOTE]
>
> **A property in both lists is hidden**
>
> `hidden_keys` always wins over `allowed_keys`.

## Which properties customers can use

A property is available to customers only when all of these hold:

* The feature is turned on, and the property passes your show and hide lists.
* **It is not an aggregation property.** Properties a meter aggregates on are always hidden: the `field` of a `SUM`, `MAX`, `AVG`, `LATEST` or `SUM_WITH_MULTIPLIER` meter, and any property used in a meter's `expression`. This applies across every meter on the same event. The fields of `COUNT` and `COUNT_UNIQUE` meters are identifiers, not quantities, so they stay available.
* **Its name uses only letters, numbers, `_` and `.`**

> [!WARNING]
>
> **Send property values as strings to group or filter by them**
>
> Grouping and filtering read property values as strings. A property sent as a number, such as `"version": 2`, groups as if the property were missing and matches no filter. Send `"version": "2"` instead.

The properties endpoint builds its list from the customer's most recent usage of each meter in the requested date range. A property that only appears on older events may not be listed.

## API

A portal front end calls these endpoints with the customer's session token. Request bodies take `start_time`, `end_time` and optional `feature_ids`.

| Method | Path | Description |
| - | - | - |
| `POST` | `/v1/customer/portal/analytics/properties` | Properties the customer can group and filter by, most used first |
| `POST` | `/v1/customer/portal/analytics/properties/values` | Values of one property, most used first. Takes `key`, an optional `prefix`, and `limit` (1 to 200, default 50) |
| `POST` | `/v1/customer/portal/analytics/revenue` | Accepts `group_by: ["properties.<key>"]` and `property_filters` |
| `POST` | `/v1/customer/portal/analytics/cost` | Accepts `property_filters` |

```bash theme={null}
curl --request POST \
  --url https://api.cloud.flexprice.io/v1/customer/portal/analytics/revenue \
  --header 'X-Session-Token: <session_token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "start_time": "2026-10-01T00:00:00Z",
    "end_time": "2026-10-31T00:00:00Z",
    "window_size": "DAY",
    "group_by": ["properties.region"],
    "property_filters": { "cloud_provider": ["aws"] },
    "expand": ["price"]
  }'
```

A property the customer cannot use returns `400` with `property key "<key>" is not available`.

The same lookups exist for your own API key at `/v1/meter-usage/properties` and `/v1/meter-usage/properties/values`. They take an `external_customer_id` and do not apply the show and hide lists, so you can see every property. Without `external_customer_id`, the properties lookup covers the whole environment.

## Limitations

* Grouping by a property with thousands of values returns every group, which makes the response large and slower to load.
* After you change the setting, open portal sessions can take up to a minute to reflect it.

## Related resources

> [card] [Customer Portal](https://docs.flexprice.io/docs/customers/customer-portal)
>
> Sessions, sections and the security model

> [card] [Portal configuration](https://docs.flexprice.io/docs/customers/customer-portal/configuration.md)
>
> The full configuration schema and theming

> [card] [Portal API reference](https://docs.flexprice.io/docs/customers/customer-portal/api-reference.md)
>
> Every endpoint available to a portal session

> [card] [Metered features](https://docs.flexprice.io/docs/event-ingestion/creating-a-metered-feature.md)
>
> How meters aggregate event properties


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.