Document project.metricsByDeployment

content/access/projects.md

@@ -61,20 +61,27 @@ Returns the project's current monthly usage rolled up by resource type. The
 same data drives the project dashboard and feeds the
 [billing report](/billing/usage-reports/).
 
-For charts rather than a single rollup, two API functions return time-series
-over a `timeRange` (`7d`, `30d`, or `90d`):
+For charts rather than a single rollup, these API functions return time-series:
 
 - **`project.metrics`** — CPU, memory, disk, egress, replica, and static-storage
-  usage over time, the series behind the project dashboard.
-- **`project.storageMetrics`** — static-site storage held over time.
+  usage over time (`timeRange` `7d`, `30d`, or `90d`), the series behind the
+  project dashboard.
+- **`project.metricsByDeployment`** — daily CPU, memory, pod egress, requests,
+  and static storage, one series per current deployment. It reads the
+  per-deployment samples already collected for deployment charts, so `timeRange`
+  is `7d` or `30d` (that history is kept for 30 days). Disk, replicas, cache
+  egress, and WAF egress stay on `project.metrics`; they are not recorded per
+  deployment.
+- **`project.storageMetrics`** — static-site storage held over time (`timeRange`
+  `7d`, `30d`, or `90d`).
 
 ```bash
 curl https://api.deploys.app/project.metrics \
   -H "Authorization: Bearer $DEPLOYS_TOKEN" \
   -d '{ "project": "acme", "timeRange": "30d" }'
 ```
 
-Both need only `project.get`.
+These need only `project.get`.
 
 ## Deleting a project
 

content/access/roles.md

@@ -69,9 +69,9 @@ Some actions don't have their own permission — they ride on a broader one.
 `deployment.metrics`, `deployment.revisions`, `deployment.rollback`,
 `deployment.pause`, and `deployment.resume` are all covered by `deployment.get`
 or `deployment.deploy`; `registry.delete` / `deleteManifest` / `untag` are
-covered by `registry.push`; `project.usage` and `project.metrics` by
-`project.get`. Granting the made-up string does nothing — grant the broader
-permission instead.
+covered by `registry.push`; `project.usage`, `project.metrics`, and
+`project.metricsByDeployment` by `project.get`. Granting the made-up string
+does nothing — grant the broader permission instead.
 
 `.list` and `.get` differ in **what data they return**, not just scope:
 `deployment.list` is a non-sensitive index — it returns each deployment's name,