getProjectsPeopleUtilization
Analyze user and project utilization data, including billable and non-billable time, availability, and metrics. Customize reports with filters, sorting, and grouping for detailed insights.
Instructions
Return the user utilization data. This endpoint provides detailed information about user utilization, including billable and non-billable time, availability, and various utilization metrics.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| IncludeCompletedTasks | No | include completed tasks | |
| companyIds | No | filter by company ids | |
| endDate | No | filter by end date | |
| fields[users] | No | specific user fields to include | |
| fields[utilizations] | No | specific utilization fields to include | |
| groupBy | No | group by | |
| include | No | include additional data | |
| includeArchivedProjects | No | include archived projects | |
| includeClients | No | include client users | |
| includeCollaborators | No | include collaborators | |
| includeTotals | No | adds report summary to response | |
| includeUtilizations | No | adds report rows for individual entities | |
| isCustomDateRange | No | determine if the query is for a custom date range | |
| isReportDownload | No | generate a report document | |
| jobRoleIds | No | filter by jobrole ids | |
| legacyResponse | No | return response without summary and its legacy body structure | |
| orderBy | No | sort by | |
| orderMode | No | group by | |
| page | No | page number | |
| pageSize | No | number of items in a page | |
| projectIds | No | filter by project ids | |
| reportFormat | No | define the format of the report | |
| searchTerm | No | filter by user first or last name | |
| selectedColumns | No | customise the report by selecting columns to be displayed | |
| skipCounts | No | skip doing counts on a list API endpoint for performance reasons | |
| sort | No | sort by (deprecated, use orderBy) | |
| sortOrder | No | order mode | |
| startDate | No | filter by start date | |
| teamIds | No | filter by team ids | |
| userIds | No | filter by userIds | |
| zoom | No | determine the type of zoom filter used to display on the report |
Implementation Reference
- src/tools/index.ts:94-95 (registration)Registration of the getProjectsPeopleUtilization tool in the toolPairs array, pairing the definition and handler function.{ definition: getProjectsPeopleMetricsPerformance, handler: handleGetProjectsPeopleMetricsPerformance }, { definition: getProjectsPeopleUtilization, handler: handleGetProjectsPeopleUtilization },
- src/tools/index.ts:46-46 (registration)Import statement for the tool's schema (definition) and handler implementation from the specific tool file.import { getProjectsPeopleUtilizationDefinition as getProjectsPeopleUtilization, handleGetProjectsPeopleUtilization } from './people/getPeopleUtilization.js';
- src/tools/index.ts:143-143 (registration)Re-export of the handler function from the tool implementation file.export { handleGetProjectsPeopleUtilization } from './people/getPeopleUtilization.js';
- Core helper function that implements the API call to retrieve projects people utilization data from '/people/utilization.json'. This is likely called by the tool handler.export async function getPeopleUtilization(params: GetPeopleUtilizationParams = {}) { const api = getApiClientForVersion('v3'); const response = await api.get('/people/utilization.json', { params }); return response.data; } export default getPeopleUtilization;
- src/utils/config.ts:252-252 (helper)The tool is listed in the 'People' group for configuration and filtering purposes.'People': ['getPeople', 'getPersonById', 'getProjectPeople', 'addPeopleToProject', 'deletePerson', 'getProjectsPeopleMetricsPerformance', 'getProjectsPeopleUtilization', 'getProjectPerson'],