List virtual users.

GET

/v1/virtual-users

const url = 'https://app.everruns.com/api/v1/virtual-users';
const options = {method: 'GET'};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request GET \
  --url https://app.everruns.com/api/v1/virtual-users

Parameters

Query Parameters

usage

One of:

string
null

VirtualUser is a durable virtual principal.

string

Allowed values: end_user service

search

string | null

include_archived

boolean | null

offset

integer | null format: int32

Zero-based page offset.

limit

integer | null format: int32

Maximum results per page.

Responses

200

Success

application/json

Response wrapper for paginated list endpoints. Includes pagination metadata along with the data array.

next_url and prev_url are populated by the [decorate_pagination_links] middleware after the handler returns, so handlers don’t need to thread the request URL into every construction site.

object

data

required

Array of items returned by the list operation.

Array<object>

Organization-scoped runtime account with its own profile and connections.

object

archived_at

Archive timestamp.

string | null format: date-time

avatar_url

Optional avatar URL for UI surfaces.

string | null

created_at

required

Creation timestamp.

string format: date-time

deleted_at

Delete timestamp.

string | null format: date-time

description

Optional description shown in management UI.

string | null

effective_owner

One of:

object
null

Effective human owner summary derived from the principal lineage.

object

required

string

kind

required

Class of principal that can hold permissions or own resources. system is reserved for platform-internal callers and is never minted via the public API.

string

Allowed values: user virtual_user system

metadata

subject_id

string | null format: uuid

required

External identifier (identity_<32-hex>). Shown as id in API.

string

locale

Default locale for unattended runs.

string | null

name

required

Display name used when the identity acts autonomously.

string

organization_id

required

Organization that owns the runtime account.

string

principal

One of:

object
null

Principal row representing this identity as a durable owner/executor.

object

required

string

kind

required

Class of principal that can hold permissions or own resources. system is reserved for platform-internal callers and is never minted via the public API.

string

Allowed values: user virtual_user system

metadata

subject_id

string | null format: uuid

status

required

Lifecycle status.

string

Allowed values: active archived deleted

timezone

Default timezone for unattended runs.

string | null

updated_at

required

Last update timestamp.

string format: date-time

usage

required

Immutable runtime account purpose.

string

Allowed values: end_user service

limit

required

Maximum number of items per page.

integer format: int32

next_url

Absolute URL for the next page, with offset advanced by limit. Omitted from the response (field absent) when this is the last page.

string | null

offset

required

Current offset (starting position).

integer format: int32

prev_url

Absolute URL for the previous page, with offset rolled back by limit. Omitted from the response (field absent) when this is the first page.

string | null

total

required

Total number of items matching the query (across all pages).

integer format: int32

Example

{
  "data": [
    {
      "effective_owner": {
        "id": "principal_01933b5a000070008000000000000001",
        "kind": "user"
      },
      "id": "identity_01933b5a000070008000000000000001",
      "organization_id": "org_example",
      "principal": {
        "id": "principal_01933b5a000070008000000000000001",
        "kind": "user"
      },
      "status": "active",
      "usage": "end_user"
    }
  ]
}

401

Authentication required

403

Permission denied