> ## Documentation Index > Fetch the complete documentation index at: https://learn.nextedy.com/llms.txt > Use this file to discover all available pages before exploring further. # Resource Capacity API > A read-only HTTP endpoint returning Nextedy GANTT resource capacity, allocation and overallocation for one or more Polarion projects over a date range. export const LastReviewed = ({date, state}) => { if (!date) return null; const formatted = new Date(`${date}T00:00:00Z`).toLocaleDateString("en-US", { year: "numeric", month: "long", day: "numeric", timeZone: "UTC" }); const label = state === "reviewed" ? `Last reviewed and confirmed up to date on ${formatted}` : `Last updated on ${formatted}`; return

{label}

; }; The resource view answers "is this team overloaded?" for one plan on one screen. The capacity endpoint answers it for a portfolio: several projects, a date range, month by month, in a form another system can consume. It is read-only and runs under the calling user's own Polarion permissions -- it can return nothing the caller could not already see. Available since version **26.9.0**. ## Request ```http theme={null} GET /polarion/gantt/api/capacity/v1 ``` | Parameter | Required | Description | | ------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `projects` | Yes | Comma-separated Polarion project IDs. | | `from` | Yes | Start of the range, `YYYY-MM-DD`, inclusive. | | `to` | Yes | End of the range, `YYYY-MM-DD`. Must not be before `from`. | | `granularity` | No | `month` (default) splits the range into calendar-month buckets. `total` returns the whole range as one bucket. Any other value is accepted and treated as `total` rather than rejected, so a typo silently collapses the buckets. | | `team` | No | Restrict the answer to one team. | ``` /polarion/gantt/api/capacity/v1?projects=Drivetrain,Chassis&from=2026-01-01&to=2026-06-30&granularity=month ``` ## Response ```json theme={null} { "schemaVersion": 1, "generatedAt": "2026-01-15T09:12:44Z", "meta": { "projectsRequested": ["Drivetrain", "Chassis"], "projectsIncluded": ["Drivetrain", "Chassis"], "complete": true, "from": "2026-01-01", "to": "2026-06-30", "granularity": "month", "unit": "perDay", "dedupEnabled": true }, "resources": [ { "resourceId": "RBS-441", "canonicalUserId": "jsmith", "name": "Jane Smith", "type": "PERSON", "periods": [ { "from": "2026-01-01", "to": "2026-01-31", "allocatedHours": 184.0, "availableHours": 176.0, "overallocationHours": 8.0, "utilizationPct": 105 } ] }, { "resourceId": "RBS-12", "name": "Firmware Group", "type": "PHANTOM", "absoluteCapacity": 60.0, "capacityUnit": "perDay", "periods": [ { "from": "2026-01-01", "to": "2026-01-31", "allocatedHours": 990.0, "availableHours": 1320.0, "overallocationHours": 0.0, "utilizationPct": 75 } ] } ] } ``` ### Top Level | Field | Description | | --------------- | ----------------------------------------------------------------------- | | `schemaVersion` | `1`. Read it before anything else and refuse a version you do not know. | | `generatedAt` | ISO instant the answer was produced. | | `meta` | What was asked for and what was answered -- see below. | | `resources` | One row per resource. | ### `meta` | Field | Description | | --------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `team` | The team filter that was applied. Absent when the request named no team. | | `projectsRequested` | The project IDs as asked for. | | `projectsIncluded` | The project IDs actually covered by the figures. | | `complete` | `false` when a requested project was left out. Never present a partial sum as a total without checking this. | | `from`, `to`, `granularity` | The range and bucketing that were applied. | | `unit` | How declared capacity was read for this answer -- `perDay` or `perPeriodAbsolute`. The hour figures themselves are always hours. | | `dedupEnabled` | `false` when identity mapping is not configured, meaning one person may appear as more than one row. See [Map Resources to Polarion Users](/gantt/guides/resources/resource-identity-mapping). | ### A Resource Row | Field | Description | | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `resourceId` | The resource's own identifier. | | `canonicalUserId` | The deduplication key on a `PERSON` row. Omitted on a `PHANTOM` row. | | `name` | Display name. | | `type` | `PERSON` -- resolves to a Polarion user. `PHANTOM` -- a resource that is not a user, such as a department. | | `absoluteCapacity` | The capacity the resource declares for itself, reported only where that figure is what the row was aggregated against. Absent on a `PERSON` row whose availability came from a working calendar, and on a resource declaring nothing. | | `capacityUnit` | `perDay` or `perPeriodAbsolute`. Absent alongside an absent `absoluteCapacity`. See [Declare Resource Capacity in Hours per Day](/gantt/guides/calendars/resource-capacity-field). | | `periods` | One bucket per calendar month, or a single bucket under `granularity=total`. | ### A Period Bucket | Field | Description | | --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | | `from`, `to` | The bucket's own range. | | `allocatedHours` | Hours allocated to this resource within the bucket. Always present. | | `availableHours` | Hours the resource can supply. **Omitted** where availability could not be determined. | | `overallocationHours` | `allocatedHours` minus `availableHours`, floored at zero. Omitted alongside an omitted `availableHours`. | | `utilizationPct` | `allocatedHours` over `availableHours` as a rounded percentage. Omitted where available hours are zero, and alongside an omitted `availableHours`. | **A Missing `availableHours` Is Not Zero** The response omits its null fields rather than writing them out, so an undetermined availability shows up as the **key being absent** -- not as `"availableHours": null`. A consumer testing for `null` will not catch it, and one that reads the missing value as zero reports the resource as infinitely overallocated. Test for presence, not for null. The same applies to `overallocationHours`, `utilizationPct` and `canonicalUserId`. ## How Available Hours Are Derived Which of the two sources a row is aggregated against depends on what the resource resolved to. This is the same rule the resource view applies on screen, so the two do not disagree: * A **`PERSON`** row that resolves to a Polarion user with a working calendar takes its availability from that calendar, and reports no `absoluteCapacity`. * Every other row -- a `PHANTOM` department, or a person with no calendar behind them -- uses the declared figure, which is also what `absoluteCapacity` then reports. For a row using a declared `perDay` capacity, available hours are that figure multiplied by the working days of the bucket, counted **Monday to Friday**. Plant holidays are not subtracted for those rows in this version of the endpoint, so a bucket containing a shutdown reports more availability than the plan itself would. Where a resource has no calendar to supply one, allocated hours are accumulated against an assumed **eight-hour** working day. ## Errors Errors carry a JSON body of the form `{"error": ""}`. | Status | Message | Cause | | ------ | -------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- | | `400` | `Missing required parameters: projects, from, to.` | One of the three required parameters was absent. | | `400` | `from/to must be ISO dates (YYYY-MM-DD).` | A date could not be parsed. | | `400` | `'to' must not be before 'from'.` | The range runs backwards. | | `403` | `Project not accessible: ` | A requested project cannot be read by the caller. The endpoint refuses rather than returning a partial sum. | | `500` | `Request failed.` | The request could not be completed. | ## Related Pages * [Resource Breakdown Structure](/gantt/concepts/resource-breakdown-structure) -- where declared capacity and resource identity come from * [Resource Hierarchy and Identity Properties](/gantt/reference/configuration/resource-hierarchy-properties) -- the properties that decide `dedupEnabled` and `absoluteCapacity` * [Declare Resource Capacity in Hours per Day](/gantt/guides/calendars/resource-capacity-field) * [Set Up the Resource View](/gantt/guides/resources/resource-view) -- the same figures for one plan on screen