# List virtual users.

Source: <https://everruns.com/docs/api/operations/list_virtual_users/>

GET

/v1/virtual-users

Select code samplecURL (shell:curl)

```js
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);
}
```

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

* Production APIapp.everruns.com/api/v1/virtual-users

## Parameters

### Query Parameters

**usage**

One of:

* string

  VirtualUser is a durable virtual principal.

  string

  Allowed values: end\_user service

* null

  null

**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

Media typeapplication/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

  Effective human owner summary derived from the principal lineage.

  object

  **id**

  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

* null

  null

**id**

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

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

  object

  **id**

  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

* null

  null

**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

```json
{
  "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