> ## 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 series

> Returns employee stat series and range totals for a date range, keyed by employee ID. Discover definitions with POST /c/{companyId}/stats/metadata/search. Omit both statTypes and statMetadataIds to select all non-archived definitions; when both are supplied, a definition must match both. Employees and periods with no recorded data are omitted. Set include.data to false for range totals without period buckets. This response is not paginated. 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/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/search:
    post:
      tags:
        - Stats
      summary: Search employee stat series
      description: >-
        Returns employee stat series and range totals for a date range, keyed by
        employee ID. Discover definitions with POST
        /c/{companyId}/stats/metadata/search. Omit both statTypes and
        statMetadataIds to select all non-archived definitions; when both are
        supplied, a definition must match both. Employees and periods with no
        recorded data are omitted. Set include.data to false for range totals
        without period buckets. This response is not paginated. 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.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/SearchStatsRequest'
      responses:
        '200':
          description: >-
            Stats keyed by employee ID, limited to employees the caller can
            access
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchStatsResponse'
        '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:
    SearchStatsRequest:
      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
        statMetadataIds:
          type: array
          items:
            type: string
            format: uuid
          description: >-
            Stat definition UUIDs to load. An omitted or empty array adds no ID
            restriction. When statTypes is also supplied, definitions must match
            both selections. Unknown IDs match no data.
          title: Stat definition IDs
          example:
            - 11111111-1111-4111-8111-111111111111
        statTypes:
          type: array
          items:
            type: string
          minItems: 1
          description: >-
            Stat identifiers to load, global or workspace custom. Omit to add no
            identifier restriction. When statMetadataIds is also supplied,
            definitions must match both selections. Unknown identifiers match no
            data.
          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 loaded within the set the caller can
            access. This filter never grants access to more employees.
          title: Employee filter
          example:
            query: Avery
        periodLength:
          type:
            - string
            - 'null'
          enum:
            - day
            - week
            - month
            - year
            - null
          description: >-
            Aggregation period for the data points. Null aggregates the entire
            date range into one bucket; omit to derive a period from the date
            range.
          title: Period length
          example: week
        include:
          type: object
          properties:
            data:
              type: boolean
              default: true
              description: >-
                True to return the period buckets of each series. False returns
                only the range totals, which makes the response much smaller.
                Defaults to true.
              title: Include period buckets
              example: true
          description: Optional parts of the JSON response. Does not affect CSV exports.
          title: Additional response details
          example:
            data: false
      required:
        - dateRange
      title: Employee stat series request
      description: >-
        Date range, stat selection, and employee filter for series or CSV
        output.
      example:
        dateRange:
          from: '2026-01-01'
          to: '2026-01-31'
        timezone: UTC
        statTypes:
          - code-prs-merged
        periodLength: week
        include:
          data: true
    SearchStatsResponse:
      type: object
      properties:
        employeeStats:
          type: object
          additionalProperties:
            type: array
            items:
              $ref: '#/components/schemas/EmployeeStat'
          description: >-
            Stat series keyed by employee ID. Workspace-wide analytics access
            allows stats for all matching employees. Other callers can read
            their own stats, those of their direct and indirect reports, and
            employees covered by delegated reporting access. Employees with no
            stat data in the range are omitted.
          title: Series by employee ID
      required:
        - employeeStats
      title: Employee stat series response
      example:
        employeeStats:
          employee-avery:
            - employeeId: employee-avery
              stat: code-prs-merged
              statMetadataId: 11111111-1111-4111-8111-111111111111
              type: COUNT
              data:
                - date: '2026-01-05'
                  type: COUNT
                  value: 2
                  denominator: null
                - date: '2026-01-12'
                  type: COUNT
                  value: 3
                  denominator: null
              last: 3
              value: 5
              denominator: null
    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'
    EmployeeStat:
      type: object
      properties:
        employeeId:
          type: string
          description: Employee the stat series belongs to.
          title: Employee ID
          example: employee-avery
        stat:
          type: string
          description: Stat identifier, global or workspace-specific.
          title: Stat identifier
          example: code-prs-merged
        statMetadataId:
          type: string
          description: Stat definition ID from POST /c/{companyId}/stats/metadata/search.
          title: Stat definition ID
          example: 11111111-1111-4111-8111-111111111111
        type:
          type: string
          enum:
            - COUNT
            - AGGREGATE
            - AVERAGE
          description: >-
            How stat values aggregate over a period: COUNT sums event counts,
            AGGREGATE sums measured values and counts a denominator, AVERAGE is
            a denominator-weighted per-unit ratio.
          title: Value type
          example: COUNT
        data:
          type: array
          items:
            $ref: '#/components/schemas/StatData'
          description: >-
            Stored period buckets in ascending date order; missing periods are
            not filled with zeros. Omitted when include.data is false.
          title: Period buckets
        last:
          type: number
          description: >-
            Value of the most recent returned bucket, even if later periods have
            no data.
          title: Latest bucket value
          example: 3
        value:
          type: number
          description: >-
            Value across the full range: the sum of buckets for COUNT and
            AGGREGATE stats, or the denominator-weighted average for AVERAGE
            stats.
          title: Range value
          example: 5
        denominator:
          type:
            - number
            - 'null'
          description: Total denominator across the range, or null for COUNT stats.
          title: Range denominator
          example: null
      required:
        - employeeId
        - stat
        - statMetadataId
        - type
        - last
        - value
        - denominator
      description: One employee's series for one stat over the requested range.
      title: Employee stat series
    StatData:
      oneOf:
        - type: object
          properties:
            date:
              type: string
              description: >-
                Bucket start as YYYY-MM-DD. Calendar buckets can start before
                the requested range; only stored values inside the requested
                range contribute.
              title: Period start date
              example: '2026-01-05'
            value:
              type: number
              description: >-
                Period sum for COUNT and AGGREGATE stats, or
                denominator-weighted average for AVERAGE stats. An AVERAGE
                bucket with a zero denominator returns 0.
              title: Period value
              example: 3
            type:
              type: string
              enum:
                - COUNT
              description: COUNT sums values in the bucket.
              title: Value type
            denominator:
              type: 'null'
              description: Always null for COUNT stats.
              title: Denominator
              example: null
          required:
            - date
            - value
            - type
            - denominator
        - type: object
          properties:
            date:
              type: string
              description: >-
                Bucket start as YYYY-MM-DD. Calendar buckets can start before
                the requested range; only stored values inside the requested
                range contribute.
              title: Period start date
              example: '2026-01-05'
            value:
              type: number
              description: >-
                Period sum for COUNT and AGGREGATE stats, or
                denominator-weighted average for AVERAGE stats. An AVERAGE
                bucket with a zero denominator returns 0.
              title: Period value
              example: 3
            type:
              type: string
              enum:
                - AGGREGATE
              description: >-
                AGGREGATE sums measured values and their denominators
                separately.
              title: Value type
            denominator:
              type: number
              description: >-
                Summed denominator for the period, such as the number of
                meetings.
              title: Denominator
              example: 2
          required:
            - date
            - value
            - type
            - denominator
        - type: object
          properties:
            date:
              type: string
              description: >-
                Bucket start as YYYY-MM-DD. Calendar buckets can start before
                the requested range; only stored values inside the requested
                range contribute.
              title: Period start date
              example: '2026-01-05'
            value:
              type: number
              description: >-
                Period sum for COUNT and AGGREGATE stats, or
                denominator-weighted average for AVERAGE stats. An AVERAGE
                bucket with a zero denominator returns 0.
              title: Period value
              example: 3
            type:
              type: string
              enum:
                - AVERAGE
              description: AVERAGE divides the summed numerator by the summed denominator.
              title: Value type
            denominator:
              type: number
              description: >-
                Weight used for the period average, such as the number of pull
                requests.
              title: Denominator
              example: 2
          required:
            - date
            - value
            - type
            - denominator
      description: One aggregated period bucket of a stat series.
      title: Stat period bucket
  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.