# Find plan fit and overage opportunities

> Identify accounts close to limits, repeatedly over quota, or paying for capacity they do not use so revenue teams know who to help.

## Agent adaptation contract

- Canonical human page: https://agentry.sh/workflows/plan-fit-and-overage
- Execution mode: on_demand
- Immutable automation template: none
- Applies to: b2b-saas, devtools-api, enterprise-sales
- Required example events: quota_snapshot
- Required Agentry resources: none declared
- Do not use when:
  - Do not use until the example events are mapped to observed project signals, the current onboarding state is verified, and live event/property reads prove the required data is present.
  - Do not recommend this for products without a real revenue lifecycle or an equivalent paid-account signal.
  - Do not recommend this when the product has no stable account or workspace identity.
- Ask before using:
  - Which observed events map to quota_snapshot? Is the current onboarding state verified, and do live event/property reads show non-synthetic traffic for them?
  - Which live properties provide quota_snapshot.account_id, quota_snapshot.metric, quota_snapshot.used, quota_snapshot.limit, quota_snapshot.plan, and which stable user or account identifier joins the signals?

This is an adaptable workflow example, not an API recipe. Map event and property names to the project's saved signal map, require status: "verified" from GET /v1/projects/:project_id/onboarding, and confirm the required signals through live event/property metadata and rows. Fetch current OpenAPI or query-blueprint details before making calls. Do not infer unattended authority from this page.

## Why this matters

Quota pressure is an expansion signal. Underuse is a churn signal. Both are revenue moments that rarely show up in one place.

## What you get

- Accounts near or over quota
- Accounts underusing paid plans
- Suggested action: upsell, enablement, downgrade risk, or no action
- A dashboard CS and revenue ops can review weekly

## Walk through it

**You:**
> Which accounts are on the wrong plan?

**Agent:**
> I'll rank quota usage by account and plan.

```text
Endpoint: POST /v1/projects/:project_id/analytics/query
Exact shape: /v1/openapi.json?path=%2Fv1%2Fprojects%2F%7Bproject_id%7D%2Fanalytics%2Fquery&method=post
Custom HogQL goes in the OpenAPI-defined `query` field.
Concept fields:
  query: "SELECT properties.account_id AS account, properties.plan AS plan, properties.metric AS metric, argMax(toFloat(properties.used), timestamp) AS used, argMax(toFloat(properties.limit), timestamp) AS limit, used / nullIf(limit, 0) AS utilization FROM events WHERE event = 'quota_snapshot' AND timestamp > now() - INTERVAL 14 DAY GROUP BY account, plan, metric ORDER BY utilization DESC LIMIT 50"
```

## The output

The agent returns accounts grouped into expansion, risk, and healthy buckets. It should avoid treating temporary spikes as expansion without recent trend.

## Setting it up

Emit a periodic `quota_snapshot` event from billing or usage metering. Include current plan and metric names.

## Variations

- *"Only show enterprise accounts."*
- *"Find accounts over 80% for three days in a row."*
- *"Publish a quota-health board for CS."*