> ## Documentation Index
> Fetch the complete documentation index at: https://help.gowindmill.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Search employee stat totals

> Returns one page of employees with their totals for the requested stats over a date range. Employees with no data in the range are included with values of 0. Select 1 to 50 stat identifiers, then optionally filter by totals and sort by a selected stat or employee name. Pagination starts at page 1, with at most 100 employees per page. Request include.total for the count, include.aggregates for statistics across all matching employees, or include.rankOf for one employee's position across all pages. Viewing stats for all employees requires workspace-wide analytics access. Other callers can read their own stats and those of their direct and indirect reports, plus employees covered by delegated reporting access. Employee filters only narrow that access.



## OpenAPI

````yaml https://api.gowindmill.com/api/v2/openapi.json post /c/{companyId}/stats/employees/search
openapi: 3.1.0
info:
  title: Windmill API
  version: 2.0.0
  description: >-
    Use the Windmill API to integrate your systems, automate workflows, and
    build applications on your organization's data. Authenticate with an API key
    or OAuth access token. Each request uses the authenticated user's
    permissions within the selected workspace.
servers:
  - url: https://api.gowindmill.com/api/v2
security:
  - bearerAuth: []
paths:
  /c/{companyId}/stats/employees/search:
    post:
      tags:
        - Stats
      summary: Search employee stat totals
      description: >-
        Returns one page of employees with their totals for the requested stats
        over a date range. Employees with no data in the range are included with
        values of 0. Select 1 to 50 stat identifiers, then optionally filter by
        totals and sort by a selected stat or employee name. Pagination starts
        at page 1, with at most 100 employees per page. Request include.total
        for the count, include.aggregates for statistics across all matching
        employees, or include.rankOf for one employee's position across all
        pages. Viewing stats for all employees requires workspace-wide analytics
        access. Other callers can read their own stats and those of their direct
        and indirect reports, plus employees covered by delegated reporting
        access. Employee filters only narrow that access.
      operationId: stats.employees.search
      parameters:
        - schema:
            type: string
            minLength: 1
            maxLength: 128
            description: >-
              Company ID. A URL slug is also accepted. The caller must have
              access to this company.
            title: Company ID
            example: company-acme
          required: true
          description: >-
            Company ID. A URL slug is also accepted. The caller must have access
            to this company.
          name: companyId
          in: path
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SearchEmployeeStatTotalsRequest'
      responses:
        '200':
          description: One page of employees with their stat totals
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchEmployeeStatTotalsResponse'
        '400':
          description: Bad request or request validation failed
          content:
            application/json:
              schema:
                anyOf:
                  - type: object
                    properties:
                      error:
                        type: object
                        properties:
                          code:
                            type: string
                            enum:
                              - BAD_REQUEST
                          message:
                            type: string
                          requestId:
                            type: string
                        required:
                          - code
                          - message
                          - requestId
                    required:
                      - error
                  - type: object
                    properties:
                      error:
                        type: object
                        properties:
                          code:
                            type: string
                            enum:
                              - VALIDATION_ERROR
                          message:
                            type: string
                          requestId:
                            type: string
                          details:
                            type: array
                            items:
                              type: object
                              properties:
                                path:
                                  type: array
                                  items:
                                    anyOf:
                                      - type: string
                                      - type: number
                                message:
                                  type: string
                              required:
                                - path
                                - message
                        required:
                          - code
                          - message
                          - requestId
                          - details
                    required:
                      - error
        '401':
          description: >-
            Authentication is missing or invalid. Send a valid API key or OAuth
            access token in the Authorization: Bearer <TOKEN> header before
            retrying.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        enum:
                          - UNAUTHORIZED
                      message:
                        type: string
                      requestId:
                        type: string
                    required:
                      - code
                      - message
                      - requestId
                required:
                  - error
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        enum:
                          - FORBIDDEN
                      message:
                        type: string
                      requestId:
                        type: string
                    required:
                      - code
                      - message
                      - requestId
                required:
                  - error
        '404':
          description: Not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        enum:
                          - NOT_FOUND
                      message:
                        type: string
                      requestId:
                        type: string
                    required:
                      - code
                      - message
                      - requestId
                required:
                  - error
        '429':
          description: >-
            The API-client request budget is exhausted. API keys allow 500
            requests per minute per key; OAuth clients allow 500 per minute per
            client and workspace. Reads and writes share the budget. One HTTP
            request counts once, including bulk requests. Wait for the
            Retry-After delay before retrying.
          headers:
            Retry-After:
              description: Number of seconds to wait before retrying the request.
              required: true
              schema:
                type: integer
                minimum: 0
                example: 42
            RateLimit:
              description: >-
                Current request budget: limit is the maximum count, remaining is
                the unused count, and reset is seconds until the window resets,
                not a timestamp.
              required: true
              schema:
                type: string
                example: limit=500, remaining=0, reset=42
            RateLimit-Policy:
              description: >-
                Request limit and window length in seconds, formatted as
                <limit>;w=<seconds>.
              required: true
              schema:
                type: string
                example: 500;w=60
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        enum:
                          - RATE_LIMITED
                      message:
                        type: string
                      requestId:
                        type: string
                    required:
                      - code
                      - message
                      - requestId
                required:
                  - error
      security:
        - bearerAuth: []
components:
  schemas:
    SearchEmployeeStatTotalsRequest:
      type: object
      properties:
        dateRange:
          anyOf:
            - type: object
              properties:
                range:
                  type: string
              required:
                - range
            - type: object
              properties:
                from:
                  type: string
                to:
                  type: string
              required:
                - from
                - to
        timezone:
          type: string
          description: >-
            IANA timezone used to resolve the date range (e.g.
            "America/New_York"). Defaults to UTC.
          title: Timezone
          example: America/New_York
        statTypes:
          type: array
          items:
            type: string
            minLength: 1
            maxLength: 100
            pattern: ^[a-z0-9]+(-[a-z0-9]+)*$
            description: >-
              Kebab-case identifier of a global Windmill stat or a workspace
              custom stat. Discover identifiers with POST
              /c/{companyId}/stats/metadata/search.
            title: Stat identifier
            example: code-prs-merged
          minItems: 1
          maxItems: 50
          description: >-
            Stat identifiers to total, global or workspace custom. Each row
            returns its stats in this order. Unknown identifiers total 0.
          title: Stat identifiers
          example:
            - code-prs-merged
        employee:
          type: object
          properties:
            hasDirectReports:
              type:
                - boolean
                - 'null'
            hasManager:
              type:
                - boolean
                - 'null'
            employeeGroupId:
              type:
                - string
                - 'null'
            employeeGroupIds:
              type:
                - array
                - 'null'
              items:
                type: string
            employeeGroupIdSets:
              type:
                - array
                - 'null'
              items:
                type: array
                items:
                  type: string
                minItems: 1
            jobTitle:
              type:
                - string
                - 'null'
            jobTitles:
              type:
                - array
                - 'null'
              items:
                type: string
            countries:
              type:
                - array
                - 'null'
              items:
                type: string
            emails:
              type:
                - array
                - 'null'
              items:
                type: string
            emailDomains:
              type:
                - array
                - 'null'
              items:
                type: string
            employeeId:
              type:
                - string
                - 'null'
            employeeIds:
              type:
                - array
                - 'null'
              items:
                type: string
            excludedEmployeeId:
              type:
                - string
                - 'null'
            excludedEmployeeIds:
              type:
                - array
                - 'null'
              items:
                type: string
            managerId:
              type:
                - string
                - 'null'
            managerIds:
              type:
                - array
                - 'null'
              items:
                type: string
            ancestorManagerId:
              type:
                - string
                - 'null'
            ancestorManagerIds:
              type:
                - array
                - 'null'
              items:
                type: string
            indirectManagerId:
              type:
                - string
                - 'null'
            indirectManagerIds:
              type:
                - array
                - 'null'
              items:
                type: string
            isMember:
              type:
                - boolean
                - 'null'
            memberRole:
              type:
                - string
                - 'null'
              enum:
                - admin
                - hr-admin
                - integration-manager
                - data-analyst
                - team-member
                - null
            query:
              type:
                - string
                - 'null'
            includeArchived:
              type:
                - boolean
                - 'null'
            onlyArchived:
              type:
                - boolean
                - 'null'
            includeExternalOrgs:
              type:
                - boolean
                - 'null'
            platformAccess:
              type:
                - string
                - 'null'
              enum:
                - HAS_ACCESS
                - INVITE_PENDING
                - NO_ACCESS
                - null
            startDate:
              anyOf:
                - type: object
                  properties:
                    range:
                      type: string
                  required:
                    - range
                - type: object
                  properties:
                    from:
                      type: string
                    to:
                      type: string
                  required:
                    - from
                    - to
                - type: 'null'
            isAccountAdmin:
              type:
                - boolean
                - 'null'
            hasIntegrationIds:
              type:
                - array
                - 'null'
              items:
                type: string
            lacksIntegrationIds:
              type:
                - array
                - 'null'
              items:
                type: string
            and:
              type: array
              items:
                $ref: '#/components/schemas/CoreEmployeeFilter'
            or:
              type: array
              items:
                $ref: '#/components/schemas/CoreEmployeeFilter'
          description: >-
            Limits which employees are returned within the set the caller can
            access. This filter never grants access to more employees.
          title: Employee filter
          example:
            query: Avery
        search:
          type: string
          maxLength: 200
          description: >-
            Text that matches the employee name, preferred name, or email
            username.
          title: Employee search text
          example: Avery
        where:
          type: array
          items:
            type: object
            properties:
              stat:
                type: string
                minLength: 1
                maxLength: 100
                pattern: ^[a-z0-9]+(-[a-z0-9]+)*$
                description: Stat to compare. It must be one of statTypes.
                title: Stat identifier
                example: code-prs-merged
              operator:
                type: string
                enum:
                  - lt
                  - lte
                  - eq
                  - gt
                  - gte
                description: Numeric comparison to apply to the range value.
                title: Comparison operator
                example: gte
              value:
                type: number
                description: Value to compare the stat total with.
                title: Comparison value
                example: 1
            required:
              - stat
              - operator
              - value
          maxItems: 10
          description: >-
            Conditions on stat totals. An employee matches only when every
            condition is true. Each condition compares the value that a row
            returns: the weighted average for AVERAGE stats, and 0 for an
            employee with no data.
          title: Stat total conditions
          example:
            - stat: code-prs-merged
              operator: gte
              value: 1
        sort:
          type: object
          properties:
            stat:
              type:
                - string
                - 'null'
              minLength: 1
              maxLength: 100
              pattern: ^[a-z0-9]+(-[a-z0-9]+)*$
              description: >-
                Stat to sort by. It must be one of statTypes. Null sorts by
                employee name.
              title: Sort stat identifier
              example: code-prs-merged
            direction:
              type: string
              enum:
                - asc
                - desc
              description: Ascending or descending order.
              title: Sort direction
              example: desc
          default:
            stat: null
            direction: asc
          required:
            - stat
            - direction
          description: >-
            Sort order. Employees with equal values stay in name order. Defaults
            to name ascending.
          title: Sort order
          example:
            stat: code-prs-merged
            direction: desc
        page:
          type: integer
          minimum: 1
          default: 1
          description: 1-indexed page number
          title: Page number
          example: 1
        pageSize:
          type: integer
          minimum: 1
          maximum: 100
          default: 20
          description: Page size
          title: Page size
          example: 20
        include:
          type: object
          properties:
            total:
              type: boolean
              description: >-
                Set true to count all matching items and include
                pagination.total. False or omission skips the count.
              title: Include total count
              example: true
            aggregates:
              type: boolean
              description: >-
                Include aggregate values across every matching employee, before
                pagination. For AVERAGE stats, sum is null and average uses
                denominator weights.
              title: Include aggregates
              example: true
            rankOf:
              type: string
              description: >-
                Employee ID to rank. The response rank gives the position of
                that employee in the same filter and sort.
              title: Employee ID to rank
              example: employee-avery
          description: >-
            Additional results to calculate alongside the page. Omit to skip
            this work.
          title: Additional response details
          example:
            total: true
            aggregates: true
      required:
        - dateRange
        - statTypes
      additionalProperties: false
      title: Employee stat totals search request
      example:
        dateRange:
          from: '2026-01-01'
          to: '2026-01-31'
        statTypes:
          - code-prs-merged
        sort:
          stat: code-prs-merged
          direction: desc
        page: 1
        pageSize: 20
        include:
          total: true
          aggregates: true
          rankOf: employee-avery
    SearchEmployeeStatTotalsResponse:
      type: object
      properties:
        results:
          type: array
          items:
            $ref: '#/components/schemas/EmployeeStatTotalsRow'
          description: >-
            One row per employee, including employees with no data in the range.
            Only employees whose analytics the caller can read are included.
          title: Employee results
        pagination:
          $ref: '#/components/schemas/SearchPaginationResponse'
        aggregates:
          type: array
          items:
            $ref: '#/components/schemas/StatTotalsAggregate'
          description: Present when include.aggregates is true. In the order of statTypes.
          title: Aggregate totals
        rank:
          type:
            - object
            - 'null'
          properties:
            position:
              type: integer
              description: 1-based position in the sorted results across all pages.
              title: Position
              example: 1
          required:
            - position
          description: >-
            Present when include.rankOf is set. Null when that employee does not
            match the filter or the caller cannot access them.
          title: Employee rank
          example:
            position: 1
      required:
        - results
        - pagination
      additionalProperties: false
      title: Employee stat totals search response
    CoreEmployeeFilter:
      type: object
      properties:
        hasDirectReports:
          type:
            - boolean
            - 'null'
        hasManager:
          type:
            - boolean
            - 'null'
        employeeGroupId:
          type:
            - string
            - 'null'
        employeeGroupIds:
          type:
            - array
            - 'null'
          items:
            type: string
        employeeGroupIdSets:
          type:
            - array
            - 'null'
          items:
            type: array
            items:
              type: string
            minItems: 1
        jobTitle:
          type:
            - string
            - 'null'
        jobTitles:
          type:
            - array
            - 'null'
          items:
            type: string
        countries:
          type:
            - array
            - 'null'
          items:
            type: string
        emails:
          type:
            - array
            - 'null'
          items:
            type: string
        emailDomains:
          type:
            - array
            - 'null'
          items:
            type: string
        employeeId:
          type:
            - string
            - 'null'
        employeeIds:
          type:
            - array
            - 'null'
          items:
            type: string
        excludedEmployeeId:
          type:
            - string
            - 'null'
        excludedEmployeeIds:
          type:
            - array
            - 'null'
          items:
            type: string
        managerId:
          type:
            - string
            - 'null'
        managerIds:
          type:
            - array
            - 'null'
          items:
            type: string
        ancestorManagerId:
          type:
            - string
            - 'null'
        ancestorManagerIds:
          type:
            - array
            - 'null'
          items:
            type: string
        indirectManagerId:
          type:
            - string
            - 'null'
        indirectManagerIds:
          type:
            - array
            - 'null'
          items:
            type: string
        isMember:
          type:
            - boolean
            - 'null'
        memberRole:
          type:
            - string
            - 'null'
          enum:
            - admin
            - hr-admin
            - integration-manager
            - data-analyst
            - team-member
            - null
        query:
          type:
            - string
            - 'null'
        includeArchived:
          type:
            - boolean
            - 'null'
        onlyArchived:
          type:
            - boolean
            - 'null'
        includeExternalOrgs:
          type:
            - boolean
            - 'null'
        platformAccess:
          type:
            - string
            - 'null'
          enum:
            - HAS_ACCESS
            - INVITE_PENDING
            - NO_ACCESS
            - null
        startDate:
          anyOf:
            - type: object
              properties:
                range:
                  type: string
              required:
                - range
            - type: object
              properties:
                from:
                  type: string
                to:
                  type: string
              required:
                - from
                - to
            - type: 'null'
        isAccountAdmin:
          type:
            - boolean
            - 'null'
        hasIntegrationIds:
          type:
            - array
            - 'null'
          items:
            type: string
        lacksIntegrationIds:
          type:
            - array
            - 'null'
          items:
            type: string
        and:
          type: array
          items:
            $ref: '#/components/schemas/CoreEmployeeFilter'
        or:
          type: array
          items:
            $ref: '#/components/schemas/CoreEmployeeFilter'
    EmployeeStatTotalsRow:
      type: object
      properties:
        employee:
          allOf:
            - $ref: '#/components/schemas/EmployeeMinView'
            - title: Employee
              description: Basic employee profile.
        stats:
          type: array
          items:
            $ref: '#/components/schemas/EmployeeStatTotal'
          description: Totals in the order of statTypes.
          title: Stat totals
      required:
        - employee
        - stats
      title: Employee stat totals row
    SearchPaginationResponse:
      type: object
      properties:
        page:
          type: integer
          minimum: 1
          default: 1
          description: One-based page number. Defaults to 1.
          title: Page number
          example: 1
        pageSize:
          type: integer
          minimum: 1
          maximum: 100
          default: 20
          description: Maximum results per page, from 1 to 100. Defaults to 20.
          title: Page size
          example: 20
        hasMore:
          type: boolean
          description: Whether there are more matching results after this page.
          title: Has another page
          example: false
        total:
          type: integer
          minimum: 0
          description: >-
            Total matching items, independent of pagination. The route
            determines the item type.
          title: Total matches
          example: 1
      required:
        - page
        - pageSize
        - hasMore
      description: >-
        Returned page and page size, plus hasMore. Total is omitted unless
        include.total was requested.
      title: Pagination
    StatTotalsAggregate:
      type: object
      properties:
        stat:
          type: string
          description: Stat identifier.
          title: Stat identifier
          example: code-prs-merged
        sum:
          type:
            - number
            - 'null'
          description: Sum across matching employees. Null for AVERAGE stats.
          title: Sum
          example: 10
        average:
          type:
            - number
            - 'null'
          description: >-
            Average per matching employee, or the denominator-weighted average
            for AVERAGE stats. Null when no employee contributes to it.
          title: Average
          example: 5
      required:
        - stat
        - sum
        - average
      description: One stat across every employee that matches the filter, on all pages.
      title: Stat totals across employees
    EmployeeMinView:
      type: object
      properties:
        id:
          type: string
          description: >-
            Opaque employee identifier. This identifies an org-chart person, not
            a member or user.
          title: Employee ID
          example: employee-avery
        name:
          type: string
          description: Resolved display name for the employee.
          title: Display name
          example: Avery Chen
        avatarUrl:
          type:
            - string
            - 'null'
          description: Employee avatar URL, or null when no avatar is available.
          title: Avatar URL
        jobTitle:
          type:
            - string
            - 'null'
          description: Employee job title. Null indicates no recorded title.
          title: Job title
          example: Engineer
        managerId:
          type:
            - string
            - 'null'
          description: >-
            Employee ID of the direct manager, or null when no manager is
            assigned.
          title: Manager ID
          example: employee-morgan
        primaryEmail:
          type:
            - string
            - 'null'
          description: Primary employee email address, or null when none is set.
          title: Primary email
          example: avery@example.test
        phoneNumber:
          type:
            - string
            - 'null'
          description: Employee phone number, or null when unavailable.
          title: Phone number
        firstName:
          type:
            - string
            - 'null'
          description: Employee first name, or null when unavailable.
          title: First name
          example: Avery
        preferredName:
          type:
            - string
            - 'null'
          description: Employee preferred first name, or null when unavailable.
          title: Preferred name
        lastName:
          type:
            - string
            - 'null'
          description: Employee last name, or null when unavailable.
          title: Last name
          example: Chen
        isActiveMember:
          type: boolean
          description: Whether the employee has an active linked workspace membership.
          title: Has active workspace access
          example: true
      required:
        - id
        - name
        - avatarUrl
        - jobTitle
        - managerId
        - primaryEmail
        - phoneNumber
        - firstName
        - preferredName
        - lastName
        - isActiveMember
      title: Basic employee profile
      description: >-
        Identity, contact details, and workspace membership for an org-chart
        employee.
      example:
        id: employee-avery
        name: Avery Chen
        avatarUrl: null
        jobTitle: Engineer
        managerId: employee-morgan
        primaryEmail: avery@example.test
        phoneNumber: null
        firstName: Avery
        preferredName: null
        lastName: Chen
        isActiveMember: true
    EmployeeStatTotal:
      type: object
      properties:
        stat:
          type: string
          description: Stat identifier.
          title: Stat identifier
          example: code-prs-merged
        value:
          type: number
          description: >-
            Value across the range: the sum for COUNT and AGGREGATE stats, or
            the denominator-weighted average for AVERAGE stats. 0 when the
            employee has no data.
          title: Range value
          example: 5
        denominator:
          type:
            - number
            - 'null'
          description: >-
            Total denominator across the range, or null for COUNT stats and
            missing data.
          title: Range denominator
          example: null
      required:
        - stat
        - value
        - denominator
      description: One employee's total for one stat over the requested range.
      title: Employee stat total
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        Use an API key or OAuth access token. Enter only the token in the
        authorization dialog; requests send it as `Authorization: Bearer
        <TOKEN>`.


        Create an API key in your workspace's **Settings → API keys**. Keys
        start with `wm_api_` and only work in the workspace where they were
        created. Read-only keys can read data; creating, updating, or deleting
        data requires a read-write key.


        ```http

        Authorization: Bearer wm_api_example

        ```


        OAuth access tokens are issued for connected Windmill applications.


        ```http

        Authorization: Bearer <OAUTH_ACCESS_TOKEN>

        ```


        Both token types use the authenticated user's workspace permissions.
        Each endpoint's permission requirements and the sharing settings of the
        requested items still apply.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.