Get User Metadata Keys

Discover the custom metadata keys (and sample values) currently stored on tenant users.

These keys help you build filter UIs for metadata.<key> query parameters on list endpoints such as List Users. Instead of hard-coding filter fields, call this endpoint to learn which keys exist, how often they appear, and which distinct values are in use.

Use Get User Metadata Keys when:

• Building dynamic filter controls for metadata.<key>=value on List Users.
• You need to know which metadata keys exist across the tenant’s users.
• Populating dropdowns with distinct values (for example tier → gold / silver).
• Auditing custom fields before updating user metadata via Update User.

On success, the API returns each metadata key with usage counts and distinct values you can use for filter UIs.

{
  "success": true,
  "message": "Metadata keys fetched successfully",
  "data": {
    "keys": [
      {
        "key": "workspaceId",
        "count": 57,
        "totalValues": 3,
        "values": [
          "c1",
          "c2",
          "c3"
        ]
      },
      {
        "key": "tier",
        "count": 12,
        "totalValues": 2,
        "values": [
          "gold",
          "silver"
        ]
      }
    ]
  },
  "error": null
}

HTTP 200 OK means metadata keys were fetched successfully. Failures usually indicate missing tenant headers or an invalid token.

• Load metadata keys when mounting your filter bar so options stay in sync with stored user data.
• Map each returned key to a metadata.<key> query param on List Users.
• Prefer the provided values array for select inputs when the set is small.
• Re-fetch keys after bulk metadata updates so new fields appear in the UI.