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

# Get Flag Usage

> Returns daily evaluation aggregates for a flag.

Analytics are aggregated nightly by a background job. Data is not real-time.

**Retention**: clamped to your plan's analytics window (7 days on Free, 90 days on Pro/Enterprise).

## Path parameters

<ParamField path="projectId" type="string" required />

<ParamField path="flagKey" type="string" required />

## Query parameters

<ParamField query="environmentId" type="string" required>
  The environment to query.
</ParamField>

<ParamField query="from" type="string">
  Start date in `YYYY-MM-DD` format. Defaults to 29 days ago.
</ParamField>

<ParamField query="to" type="string">
  End date in `YYYY-MM-DD` format. Defaults to today. Maximum range is 90 days.
</ParamField>

## Response

<ResponseField name="flagKey" type="string" required />

<ResponseField name="environmentId" type="string" required />

<ResponseField name="from" type="string" required>
  Effective start date after plan retention clamping. May differ from the requested `from`.
</ResponseField>

<ResponseField name="to" type="string" required />

<ResponseField name="clampedFrom" type="boolean">
  Present and `true` when the requested `from` was earlier than your plan's retention window and was
  silently clamped. Absent when no clamping occurred.
</ResponseField>

<ResponseField name="rows" type="UsageDay[]" required>
  One entry per day that had evaluations. Days with zero evaluations are omitted.
</ResponseField>

Each `UsageDay`:

| Field               | Type                     | Description                              |
| ------------------- | ------------------------ | ---------------------------------------- |
| `date`              | string                   | `YYYY-MM-DD`                             |
| `totalEvaluations`  | number                   |                                          |
| `valueDistribution` | `Record<string, number>` | Value → count map                        |
| `ruleMatchCount`    | number                   | Evaluations resolved by a rule           |
| `defaultCount`      | number                   | Evaluations resolved by `defaultValue`   |
| `errorCount`        | number                   | Evaluations that returned `ERROR` reason |

<RequestExample>
  ```bash theme={null}
  curl "https://nest.feather.mupeni.dev/v1/projects/proj_01hx.../flags/new-checkout/usage?environmentId=env_01hx...&from=2024-04-01&to=2024-04-07" \
    -H "Authorization: Bearer <server_key>"
  ```
</RequestExample>

<ResponseExample>
  ```json 200 (no clamping) theme={null}
  {
    "flagKey": "new-checkout",
    "environmentId": "env_01hx...",
    "from": "2024-04-01",
    "to": "2024-04-07",
    "rows": [
      {
        "date": "2024-04-01",
        "totalEvaluations": 14823,
        "valueDistribution": { "true": 7200, "false": 7623 },
        "ruleMatchCount": 7200,
        "defaultCount": 7623,
        "errorCount": 0
      }
    ]
  }
  ```

  ```json 200 (from clamped by plan retention) theme={null}
  {
    "flagKey": "new-checkout",
    "environmentId": "env_01hx...",
    "from": "2024-03-27",
    "to": "2024-04-03",
    "clampedFrom": true,
    "rows": []
  }
  ```
</ResponseExample>