Identity records for everyone and everything that writes to your workspace. Most resources return the id of the actor that created and last updated them; look that id up here to get a display name and to tell a person apart from an agent or an automated process. Actor ids are UUIDs, unlike the short ids used everywhere else in this API. This surface is read-only.
List Actors
List actors. Returns a paginated envelope (data, total, limit, hasMore, nextCursor). Filterable by 4 fields. Ordered by displayName unless you pass sort.
Required scope: actors:read
query Parameters
sortField to sort by. Prefix with - for descending (-createdAt); a createdAt:desc / createdAt:asc suffix works too, but never both markers at once. Default: displayName.
cursorOpaque cursor for the next page (the envelope nextCursor).
limitItems per page (1–200, default 50). A larger value is clamped to the cap rather than rejected, so always follow nextCursor instead of assuming one page held everything.
includeTotalWhen true, the response envelope includes the total number of matching rows. Omit it for cheaper pagination.
id[eq]Filter where id equals.
id[in]Filter where id is one of (comma-separated list).
type[eq]Filter where type equals.
type[in]Filter where type is one of (comma-separated list).
memberId[eq]Filter where memberId equals.
memberId[in]Filter where memberId is one of (comma-separated list).
agentId[eq]Filter where agentId equals.
agentId[in]Filter where agentId is one of (comma-separated list).
List Actors › Responses
OK
The page of results.
totalTotal rows matching the query (across pages).
limithasMorenextCursorOpaque cursor for the next page; null on the last page.
Get Actor
Retrieve a single Actor by id.
Required scope: actors:read
path Parameters
id^[0-9A-Za-z_!]+$ · requiredId of the Actor.
Get Actor › Responses
OK
idActor id. A UUID — unlike the short ids used elsewhere in this API. This is the value returned as createdByActorId, updatedByActorId and actorId on other resources.
typeWhat kind of writer this is: "human" a person, "agent" an autonomous integration, "automation" a workspace rule, "recurringTask" a repeating task rule, "cron" a scheduled maintenance job, "outboxRetry" a retried delivery, "systemDefault" an unattributed server write. Branch on this to tell a person's edit from an automated one.
displayNameName to show for this actor: the person's name, the agent's name, or a label for a server process. A cached convenience copy that can briefly lag a rename, so treat the member or agent record as authoritative when you have it. "Deleted member" once the underlying person has been erased.
memberIdThe person behind this actor, when type is "human" — look it up on /members for name, avatar, role and status. Null for every other type, and null once the person has been erased.
agentIdThe agent behind this actor, when type is "agent". Null for every other type, and null once the agent has been deleted.
tombstonedAtWhen the person or agent behind this actor was permanently erased. The actor survives so past attribution stays intact, but it no longer identifies anyone: memberId and agentId are cleared and displayName becomes a placeholder. Null for every live actor.