Skip to main content
POST
Search stat definitions

Authorizations

Authorization
string
header
required

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.

OAuth access tokens are issued for connected Windmill applications.

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.

Path Parameters

companyId
string
required

Company ID. A URL slug is also accepted. The caller must have access to this company.

Required string length: 1 - 128
Example:

"company-acme"

Body

application/json

All supplied filters must match. Within a list, matching any value is enough.

ids
string<uuid>[]

Match any of these stat definition UUIDs. Omitted or empty adds no restriction.

Maximum array length: 100
Example:
statTypes
string[]

Match any of these stat identifiers. Omitted or empty adds no restriction.

Maximum array length: 100

Kebab-case identifier of a global Windmill stat or a workspace custom stat. Discover identifiers with POST /c/{companyId}/stats/metadata/search.

Required string length: 1 - 100
Pattern: ^[a-z0-9]+(-[a-z0-9]+)*$
Example:
valueTypes
enum<string>[]

Match any selected aggregation type. Omitted or empty matches all value types.

Maximum array length: 3

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.

Available options:
COUNT,
AGGREGATE,
AVERAGE
Example:

Case-insensitive literal text matched within the identifier, label, or description. Regular expressions and wildcard patterns are not interpreted.

Maximum string length: 200
Example:

"pull request"

isGlobal
boolean

True selects global Windmill-managed definitions; false selects this workspace's custom definitions. Omit to include both.

Example:

true

includeDisabled
boolean
default:false

Include disabled definitions alongside enabled ones. Archived definitions never match.

Example:

false

employee
Employees with stat data · object

Return only definitions with at least one recorded stat value for a matching employee whose analytics the caller can read. Any recorded date qualifies, including values of zero. Omit to list definitions even without recorded data; an empty object applies the default employee filter. This filter never expands employee access.

Example:
sort
Sort order · object

Sort order. Defaults to label ascending, with an ascending ID tie-breaker.

Example:
page
integer
default:1

1-indexed page number

Required range: x >= 1
Example:

1

pageSize
integer
default:20

Page size

Required range: 1 <= x <= 100
Example:

20

include
Additional response details · object
Example:

Response

One page of stat definitions

results
Stat definition · object[]
required

One page of matching, non-archived global or workspace stat definitions.

pagination
Pagination · object
required

Returned page and page size, plus hasMore. Total is omitted unless include.total was requested.