---
updatedAt: 2026-05-22T14:13:55.000Z
agentTools:
  projectIndex: https://docs.nebulock.io/llms.txt
---

# Get a List of Users

List identity users for your organization.

Users may be linked to zero or more actors. Use ``correlation_state`` to filter by linkage.

# OpenAPI definition

```json
{
  "openapi": "3.1.0",
  "info": {
    "title": "Entity Correlation API",
    "description": "Manage correlated identity for your organization: **actors** group related users and hosts; **users** and **hosts** can also be created and queried on their own.\n\nWhen you create or update an actor, supply a clear **description** and an accurate **risk_level** (`high`, `low`, or `escalated`). Automated agents use these fields to prioritize and interpret correlated content—treat the description as context for analysis, not an internal label. If `risk_level` is `escalated`, include a future `escalated_till` (UTC).\n\nAll routes require your organization's API key credentials (`X-API-Key-ID` and `X-API-Key-Secret` headers on each request).",
    "version": "0.0.1"
  },
  "paths": {
    "/public/v1/entities/users": {
      "get": {
        "tags": [
          "public"
        ],
        "summary": "Get a List of Users",
        "description": "List identity users for your organization.\n\nUsers may be linked to zero or more actors. Use ``correlation_state`` to filter by linkage.",
        "operationId": "get_users_public_v1_entities_users_get",
        "parameters": [
          {
            "name": "offset",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 0,
              "description": "Pagination offset (number of users to skip).",
              "default": 0,
              "title": "Offset"
            },
            "description": "Pagination offset (number of users to skip)."
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "maximum": 1000,
              "minimum": 1,
              "description": "Maximum number of users to return (1–1000).",
              "default": 100,
              "title": "Limit"
            },
            "description": "Maximum number of users to return (1–1000)."
          },
          {
            "name": "user_name",
            "in": "query",
            "required": false,
            "schema": {
              "anyOf": [
                {
                  "type": "string",
                  "minLength": 1,
                  "maxLength": 1024
                },
                {
                  "type": "null"
                }
              ],
              "description": "Exact username match.",
              "title": "User Name"
            },
            "description": "Exact username match."
          },
          {
            "name": "user_email",
            "in": "query",
            "required": false,
            "schema": {
              "anyOf": [
                {
                  "type": "string",
                  "minLength": 1,
                  "maxLength": 1024
                },
                {
                  "type": "null"
                }
              ],
              "description": "Exact email address match.",
              "title": "User Email"
            },
            "description": "Exact email address match."
          },
          {
            "name": "correlation_state",
            "in": "query",
            "required": false,
            "schema": {
              "anyOf": [
                {
                  "type": "boolean"
                },
                {
                  "type": "null"
                }
              ],
              "description": "When true, only users linked to at least one actor; when false, only users not linked to any actor.",
              "title": "Correlation State"
            },
            "description": "When true, only users linked to at least one actor; when false, only users not linked to any actor."
          },
          {
            "name": "tags",
            "in": "query",
            "required": false,
            "schema": {
              "anyOf": [
                {
                  "type": "array",
                  "items": {
                    "type": "string"
                  }
                },
                {
                  "type": "null"
                }
              ],
              "description": "Return users that have any of these tags.",
              "title": "Tags"
            },
            "description": "Return users that have any of these tags."
          },
          {
            "name": "groups",
            "in": "query",
            "required": false,
            "schema": {
              "anyOf": [
                {
                  "type": "array",
                  "items": {
                    "type": "string"
                  }
                },
                {
                  "type": "null"
                }
              ],
              "description": "Return users that belong to any of these groups.",
              "title": "Groups"
            },
            "description": "Return users that belong to any of these groups."
          },
          {
            "name": "is_active",
            "in": "query",
            "required": false,
            "schema": {
              "anyOf": [
                {
                  "type": "boolean"
                },
                {
                  "type": "null"
                }
              ],
              "description": "When set, only return active users.",
              "title": "Is Active"
            },
            "description": "When set, only return active users."
          },
          {
            "name": "X-API-Key-ID",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string",
              "description": "Your API Key ID",
              "title": "X-API-Key-ID"
            },
            "description": "Your API Key ID"
          },
          {
            "name": "X-API-Key-Secret",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string",
              "description": "Your API Key Secret",
              "title": "X-API-Key-Secret"
            },
            "description": "Your API Key Secret"
          }
        ],
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UserResponse"
                }
              }
            }
          },
          "422": {
            "description": "Validation Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            }
          }
        },
        "security": [
          {
            "ApiKeyAuth": []
          },
          {
            "ApiKeySecretAuth": []
          }
        ]
      }
    }
  },
  "components": {
    "schemas": {
      "ActorUser-Output": {
        "properties": {
          "user_id": {
            "type": "string",
            "title": "User Id",
            "description": "The user ID",
            "default": ""
          },
          "user_name": {
            "type": "string",
            "title": "User Name",
            "description": "The user name",
            "default": ""
          },
          "user_email": {
            "type": "string",
            "title": "User Email",
            "description": "The user email",
            "default": ""
          },
          "first_name": {
            "type": "string",
            "title": "First Name",
            "description": "The user's first name",
            "default": ""
          },
          "last_name": {
            "type": "string",
            "title": "Last Name",
            "description": "The user's last name",
            "default": ""
          },
          "display_name": {
            "type": "string",
            "title": "Display Name",
            "description": "The user's display name",
            "default": ""
          },
          "city": {
            "type": "string",
            "title": "City",
            "description": "The user's city",
            "default": ""
          },
          "state": {
            "type": "string",
            "title": "State",
            "description": "The user's state",
            "default": ""
          },
          "country_code": {
            "type": "string",
            "title": "Country Code",
            "description": "The user's country code",
            "default": ""
          },
          "postal_address": {
            "type": "string",
            "title": "Postal Address",
            "description": "The user's postal address",
            "default": ""
          },
          "organization": {
            "type": "string",
            "title": "Organization",
            "description": "The user's organization",
            "default": ""
          },
          "department": {
            "type": "string",
            "title": "Department",
            "description": "The user's department",
            "default": ""
          },
          "division": {
            "type": "string",
            "title": "Division",
            "description": "The user's division",
            "default": ""
          },
          "credential_types": {
            "items": {
              "type": "string"
            },
            "type": "array",
            "title": "Credential Types",
            "description": "Credential types available on this user",
            "default": []
          },
          "identity_provider": {
            "type": "string",
            "title": "Identity Provider",
            "description": "The source identity provider",
            "default": ""
          },
          "source_status": {
            "type": "string",
            "title": "Source Status",
            "description": "The raw provider status for the user",
            "default": ""
          },
          "nebulock_provider_name": {
            "type": "string",
            "title": "Nebulock Provider Name",
            "description": "Integration that supplied this user (for example Okta or API).",
            "default": ""
          },
          "organization_id": {
            "type": "string",
            "maxLength": 64,
            "title": "Organization Id",
            "description": "Your organization ID.",
            "default": ""
          },
          "last_login_at": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Last Login At",
            "description": "Last login timestamp (UTC)."
          },
          "activated_at": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Activated At",
            "description": "When the user was activated in the identity provider (UTC)."
          },
          "last_updated_at": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Last Updated At",
            "description": "When the user profile was last updated (UTC)."
          },
          "idp_created_at": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Idp Created At",
            "description": "When the user was created in the identity provider (UTC)."
          },
          "created_at": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Created At",
            "description": "When this user record was created (UTC)."
          },
          "updated_at": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Updated At",
            "description": "When this user record was last updated (UTC)."
          },
          "tags": {
            "anyOf": [
              {
                "items": {
                  "type": "string"
                },
                "type": "array"
              },
              {
                "type": "null"
              }
            ],
            "title": "Tags",
            "description": "Optional tags applied to this user."
          },
          "groups": {
            "anyOf": [
              {
                "items": {
                  "type": "string"
                },
                "type": "array"
              },
              {
                "type": "null"
              }
            ],
            "title": "Groups",
            "description": "Groups or roles from the identity provider."
          },
          "group_ids": {
            "items": {
              "type": "string"
            },
            "type": "array",
            "title": "Group Ids",
            "description": "Group/OU identifiers for correlation",
            "default": []
          },
          "group_names": {
            "items": {
              "type": "string"
            },
            "type": "array",
            "title": "Group Names",
            "description": "Group display names",
            "default": []
          },
          "manager_id": {
            "type": "string",
            "title": "Manager Id",
            "description": "Manager user ID for hierarchy",
            "default": ""
          },
          "manager_name_or_login": {
            "type": "string",
            "title": "Manager Name Or Login",
            "description": "Manager display name or login",
            "default": ""
          },
          "job_title": {
            "type": "string",
            "title": "Job Title",
            "description": "Job title",
            "default": ""
          },
          "employee_number": {
            "type": "string",
            "title": "Employee Number",
            "description": "Employee number",
            "default": ""
          },
          "cost_center": {
            "type": "string",
            "title": "Cost Center",
            "description": "Cost center",
            "default": ""
          },
          "high_risk": {
            "type": "boolean",
            "title": "High Risk",
            "description": "When true, marks this user as high risk for correlation and review workflows.",
            "default": false
          }
        },
        "type": "object",
        "title": "ActorUser"
      },
      "HTTPValidationError": {
        "properties": {
          "detail": {
            "items": {
              "$ref": "#/components/schemas/ValidationError"
            },
            "type": "array",
            "title": "Detail"
          }
        },
        "type": "object",
        "title": "HTTPValidationError"
      },
      "ResponseError": {
        "properties": {
          "message": {
            "type": "string",
            "title": "Message",
            "description": "Human-readable error message"
          },
          "key": {
            "type": "string",
            "title": "Key",
            "description": "Error identification key for programmatic handling"
          },
          "debug": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Debug",
            "description": "Debug information for the error"
          }
        },
        "type": "object",
        "required": [
          "message",
          "key"
        ],
        "title": "ResponseError",
        "description": "Error Response coming back from the API"
      },
      "ResponseMeta": {
        "properties": {
          "current_page": {
            "type": "integer",
            "title": "Current Page",
            "description": "Current page number in pagination",
            "default": 1
          },
          "total_page_count": {
            "type": "integer",
            "title": "Total Page Count",
            "description": "Total number of pages available",
            "default": 0
          },
          "total_item_count": {
            "type": "integer",
            "title": "Total Item Count",
            "description": "Total number of items across all pages",
            "default": 0
          },
          "items_per_page": {
            "type": "integer",
            "title": "Items Per Page",
            "description": "Number of items displayed per page",
            "default": 10
          }
        },
        "type": "object",
        "title": "ResponseMeta",
        "description": "Basic Pagination and other metadata"
      },
      "UserResponse": {
        "properties": {
          "data": {
            "items": {
              "$ref": "#/components/schemas/ActorUser-Output"
            },
            "type": "array",
            "title": "Data",
            "description": "The list of users"
          },
          "meta": {
            "$ref": "#/components/schemas/ResponseMeta",
            "description": "Pagination metadata"
          },
          "error": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/ResponseError"
              },
              {
                "type": "null"
              }
            ],
            "description": "Error information if request failed"
          }
        },
        "type": "object",
        "required": [
          "data",
          "meta"
        ],
        "title": "UserResponse"
      },
      "ValidationError": {
        "properties": {
          "loc": {
            "items": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "integer"
                }
              ]
            },
            "type": "array",
            "title": "Location"
          },
          "msg": {
            "type": "string",
            "title": "Message"
          },
          "type": {
            "type": "string",
            "title": "Error Type"
          },
          "input": {
            "title": "Input"
          },
          "ctx": {
            "type": "object",
            "title": "Context"
          }
        },
        "type": "object",
        "required": [
          "loc",
          "msg",
          "type"
        ],
        "title": "ValidationError"
      }
    },
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key-ID",
        "description": "Your API Key ID"
      },
      "ApiKeySecretAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key-Secret",
        "description": "Your API Key Secret"
      }
    }
  },
  "security": [
    {
      "ApiKeyAuth": []
    },
    {
      "ApiKeySecretAuth": []
    }
  ]
}
```