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

# Upload custom employee stat values

> Creates or replaces up to 1000 dated employee values for one workspace custom stat definition. Create the definition first, then send its ID and employee values. Identify each employee by employeeId or by email; an email matches the employee's primary or secondary emails. The definition's aggregation type determines how values are interpreted. Repeating the same employee, date, and optional dimension replaces that value, so retries never add to totals. Omitted values are preserved. Different dimensions contribute separately to the combined daily value. The entire request succeeds or fails together. Disabled or archived definitions cannot receive values. Missing or out-of-workspace definitions, employee IDs, and emails return 404; identifiers reserved for Windmill-managed stats return 409. Read uploaded values through stat series, employee totals, or CSV export using the caller's analytics access.



## OpenAPI

````yaml https://api.gowindmill.com/api/v2/openapi.json put /c/{companyId}/stats/values
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/values:
    put:
      tags:
        - Stats
      summary: Upload custom employee stat values
      description: >-
        Creates or replaces up to 1000 dated employee values for one workspace
        custom stat definition. Create the definition first, then send its ID
        and employee values. Identify each employee by employeeId or by email;
        an email matches the employee's primary or secondary emails. The
        definition's aggregation type determines how values are interpreted.
        Repeating the same employee, date, and optional dimension replaces that
        value, so retries never add to totals. Omitted values are preserved.
        Different dimensions contribute separately to the combined daily value.
        The entire request succeeds or fails together. Disabled or archived
        definitions cannot receive values. Missing or out-of-workspace
        definitions, employee IDs, and emails return 404; identifiers reserved
        for Windmill-managed stats return 409. Read uploaded values through stat
        series, employee totals, or CSV export using the caller's analytics
        access.
      operationId: stats.values.upsert
      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/UpsertCustomStatValuesRequest'
      responses:
        '200':
          description: Number of values written
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpsertCustomStatValuesResponse'
        '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
        '409':
          description: Conflict
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        enum:
                          - CONFLICT
                      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
                            resourceId:
                              type: string
                          required:
                            - path
                            - message
                        description: >-
                          Request fields that caused the conflict, when the
                          operation identifies them. resourceId names the
                          existing resource that conflicts.
                    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:
    UpsertCustomStatValuesRequest:
      type: object
      properties:
        statMetadataId:
          type: string
          format: uuid
          description: >-
            ID of an enabled, non-archived custom definition owned by this
            workspace. Windmill-managed definitions and their identifiers cannot
            be written through this route.
          title: Custom stat definition ID
          example: 11111111-1111-4111-8111-111111111111
        values:
          type: array
          items:
            type: object
            properties:
              employeeId:
                type: string
                minLength: 1
                maxLength: 128
                description: >-
                  ID of an active employee in this workspace. Send exactly one
                  of employeeId and email.
                title: Employee ID
                example: employee-avery
              email:
                type: string
                maxLength: 320
                format: email
                description: >-
                  Email address of an active employee in this workspace. Matches
                  the employee's primary or secondary emails, ignoring letter
                  case and any +tag. Send exactly one of employeeId and email.
                title: Employee email
                example: avery@example.test
              date:
                type: string
                format: date
                description: >-
                  Calendar date for this value, YYYY-MM-DD, with a year from
                  0001 to 9999.
                title: Date
                example: '2026-01-05'
              value:
                type: number
                minimum: -9007199254740991
                maximum: 9007199254740991
                description: >-
                  Daily value for COUNT or AGGREGATE. For AVERAGE, send the
                  numerator sum, not the already-divided average; readers divide
                  by the denominator. Must be finite with absolute value at most
                  9007199254740991.
                title: Value
                example: 5
              denominator:
                type:
                  - integer
                  - 'null'
                minimum: 0
                maximum: 2147483647
                description: >-
                  Observation count, required for AGGREGATE and AVERAGE; omit or
                  use null for COUNT. A zero denominator requires a zero value.
                  Maximum 2147483647.
                title: Denominator
                example: null
              dimension:
                type: string
                minLength: 1
                maxLength: 200
                description: >-
                  Optional source key, 1 to 200 characters. Different keys store
                  separate contributions for the same employee and date; reads
                  combine them. Omit for an unkeyed daily value.
                title: Dimension
                example: project-aurora
            required:
              - date
              - value
            additionalProperties: false
          minItems: 1
          maxItems: 1000
          description: >-
            1 to 1000 values for this definition. Each employee/date/dimension
            key must be unique within the request after emails resolve to
            employees. All values are validated and written together.
          title: Employee stat values
      required:
        - statMetadataId
        - values
      additionalProperties: false
      title: Custom stat values request
      example:
        statMetadataId: 11111111-1111-4111-8111-111111111111
        values:
          - employeeId: employee-avery
            date: '2026-01-05'
            value: 5
          - email: morgan@example.test
            date: '2026-01-05'
            value: 3
    UpsertCustomStatValuesResponse:
      type: object
      properties:
        updated:
          type: integer
          minimum: 0
          description: Number of submitted values successfully created or replaced.
          title: Values written
          example: 1
      required:
        - updated
      title: Custom stat values response
  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.