--- updatedAt: 2026-05-22T14:13:55.000Z agentTools: projectIndex: https://docs.nebulock.io/llms.txt --- # Get a List of Actors Retrieve a list of actors from your organization. Each actor includes its **description**, **risk_level**, linked users, and linked hosts.Use filters to narrow results, or `search_text` for keyword search across indexed actor text. # 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/actors": { "get": { "tags": [ "public" ], "summary": "Get a List of Actors", "description": "Retrieve a list of actors from your organization. Each actor includes its **description**, **risk_level**, linked users, and linked hosts.Use filters to narrow results, or `search_text` for keyword search across indexed actor text.", "operationId": "get_actors_public_v1_entities_actors_get", "parameters": [ { "name": "search_text", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 1024 }, { "type": "null" } ], "description": "Keyword search across the actor's indexed text (names, emails, host names, tags, description, and related fields).", "title": "Search Text" }, "description": "Keyword search across the actor's indexed text (names, emails, host names, tags, description, and related fields)." }, { "name": "user_name", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 1024 }, { "type": "null" } ], "description": "Return actors linked to a user with this exact username.", "title": "User Name" }, "description": "Return actors linked to a user with this exact username." }, { "name": "user_email", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 1024 }, { "type": "null" } ], "description": "Return actors linked to a user with this exact email address.", "title": "User Email" }, "description": "Return actors linked to a user with this exact email address." }, { "name": "host_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 1024 }, { "type": "null" } ], "description": "Return actors linked to a host with this exact host ID.", "title": "Host Id" }, "description": "Return actors linked to a host with this exact host ID." }, { "name": "host_name", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 1024 }, { "type": "null" } ], "description": "Return actors linked to a host with this exact display name.", "title": "Host Name" }, "description": "Return actors linked to a host with this exact display name." }, { "name": "endpoint_uid", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 1024 }, { "type": "null" } ], "description": "Return actors linked to a host with this exact endpoint identifier from your security tools.", "title": "Endpoint Uid" }, "description": "Return actors linked to a host with this exact endpoint identifier from your security tools." }, { "name": "risk_level", "in": "query", "required": false, "schema": { "anyOf": [ { "enum": [ "high", "low", "escalated" ], "type": "string" }, { "type": "null" } ], "description": "Filter by actor risk level: `high`, `low`, or `escalated`.", "title": "Risk Level" }, "description": "Filter by actor risk level: `high`, `low`, or `escalated`." }, { "name": "nebulock_tags", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ], "description": "Return actors that have any of these platform-managed tags.", "title": "Nebulock Tags" }, "description": "Return actors that have any of these platform-managed tags." }, { "name": "tags", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ], "description": "Return actors whose combined user/host tags include any of these values.", "title": "Tags" }, "description": "Return actors whose combined user/host tags include any of these values." }, { "name": "groups", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ], "description": "Return actors whose combined user/host groups include any of these values.", "title": "Groups" }, "description": "Return actors whose combined user/host groups include any of these values." }, { "name": "is_active", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "When set, only return active actors (and apply the same filter to nested users and hosts in the response).", "title": "Is Active" }, "description": "When set, only return active actors (and apply the same filter to nested users and hosts in the response)." }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "description": "Pagination offset (number of actors to skip).", "default": 0, "title": "Offset" }, "description": "Pagination offset (number of actors to skip)." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 1000, "minimum": 1, "description": "Maximum number of actors to return (1–1000).", "default": 100, "title": "Limit" }, "description": "Maximum number of actors to return (1–1000)." }, { "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/ActorCorrelationsResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } }, "security": [ { "ApiKeyAuth": [] }, { "ApiKeySecretAuth": [] } ] } } }, "components": { "schemas": { "ActorCorrelation-Output": { "properties": { "actor_id": { "type": "string", "title": "Actor Id", "description": "Unique actor ID. Optional on create; omitted values receive a server-generated ID.", "default": "" }, "organization_id": { "type": "string", "title": "Organization Id", "description": "Your organization ID (set automatically on create).", "default": "" }, "description": { "type": "string", "title": "Description", "description": "Human-readable summary of who or what this actor represents. Automated agents use this text together with risk_level when analyzing correlated users, hosts, and security content.", "default": "" }, "primary_entity_id": { "type": "string", "title": "Primary Entity Id", "description": "Primary identifier for the actor (for example a canonical user or host ID from your environment).", "default": "" }, "primary_entity_type": { "type": "string", "title": "Primary Entity Type", "description": "Type of the primary entity (for example user, host, or service account).", "default": "" }, "nebulock_provider_name": { "type": "string", "title": "Nebulock Provider Name", "description": "Source of the record. API-created actors typically use `api`.", "default": "" }, "user_identifier": { "type": "string", "title": "User Identifier", "description": "Display label for the actor (for example an email or friendly name shown in search results).", "default": "" }, "users": { "anyOf": [ { "items": { "$ref": "#/components/schemas/ActorUser-Output" }, "type": "array" }, { "type": "null" } ], "title": "Users", "description": "Users linked to this actor." }, "hosts": { "anyOf": [ { "items": { "$ref": "#/components/schemas/ActorHost-Output" }, "type": "array" }, { "type": "null" } ], "title": "Hosts", "description": "Hosts linked to this actor." }, "searchable": { "type": "string", "title": "Searchable", "description": "Indexed text used for keyword search (derived from description, users, hosts, and tags)." }, "risk_level": { "type": "string", "title": "Risk Level", "description": "How urgently this actor should be handled: `high`, `low`, or `escalated`. Automated agents use risk_level with the description to prioritize analysis.", "default": "low" }, "escalated_till": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Escalated Till", "description": "When risk_level is `escalated`, UTC time until the escalation automatically expires." }, "nebulock_tags": { "items": { "type": "string" }, "type": "array", "title": "Nebulock Tags", "description": "Platform-managed tags on this actor." }, "all_tags": { "items": { "type": "string" }, "type": "array", "title": "All Tags", "description": "Combined tags from the actor and linked users/hosts." }, "all_groups": { "items": { "type": "string" }, "type": "array", "title": "All Groups", "description": "Combined groups from the actor and linked users/hosts." }, "created_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Created At", "description": "When this actor was created (UTC)." }, "updated_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Updated At", "description": "When this actor was last updated (UTC)." }, "modified": { "type": "boolean", "title": "Modified", "description": "Whether the actor has been modified", "default": false } }, "type": "object", "title": "ActorCorrelation" }, "ActorCorrelationsResponse": { "properties": { "data": { "items": { "$ref": "#/components/schemas/ActorCorrelation-Output" }, "type": "array", "title": "Data", "description": "The list of actor correlations" }, "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": "ActorCorrelationsResponse" }, "ActorHost-Output": { "properties": { "host_id": { "type": "string", "title": "Host Id", "description": "The host ID", "default": "" }, "organization_id": { "type": "string", "maxLength": 64, "minLength": 10, "title": "Organization Id", "description": "The organization ID", "default": "" }, "host_name": { "type": "string", "title": "Host Name", "description": "The host name", "default": "" }, "host_ip": { "type": "string", "title": "Host Ip", "description": "The host IP", "default": "" }, "nebulock_provider_name": { "type": "string", "title": "Nebulock Provider Name", "description": "Integration that supplied this host (for example EDR or API).", "default": "" }, "endpoint_uid": { "type": "string", "title": "Endpoint Uid", "description": "Endpoint identifier from your security tools.", "default": "" }, "high_risk": { "type": "boolean", "title": "High Risk", "description": "When true, marks this host as high risk for correlation and review workflows.", "default": false }, "tags": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Tags", "description": "Optional tags applied to this host." }, "groups": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Groups", "description": "Optional groups this host belongs to." }, "created_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Created At", "description": "The host creation timestamp" }, "updated_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Updated At", "description": "The host update timestamp" } }, "type": "object", "title": "ActorHost" }, "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" }, "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": [] } ] } ```