For AI agents: The documentation index is at https://docs.digitalocean.com/llms.txt. Markdown versions of pages use the same URL with index.html.md in place of the HTML page (for example, append index.html.md to the directory path instead of opening the HTML document).

Usage

client.users.list(
    user_id=None,
    sort="created_at",
    sort_direction=None,
    page=1,
    per_page=20,
)

Description

Returns the user IDs known for your team: session actor_id values, the user_id of connections that are not revoked, and actors with limit overrides. Only sessions and connections you can see count. Offset-paged with page and per_page.

Parameters

user_id string optional

User ID prefix to return. An empty value returns all users.

sort string optional

user_id|created_at|session_count|connection_count. created_at is the earliest creation time among the user's sessions, connections, and limit overrides. Defaults to created_at.

One of: created_at, user_id, session_count, connection_count

Default: created_at

sort_direction string optional

asc|desc. Defaults to desc.

One of: asc, desc

page integer optional

1-based page number. Values below 1 are treated as 1.

Min: 1

Default: 1

per_page integer optional

Page size. Defaults to 20; values above 100 are capped at 100.

Min: 1

Max: 100

Default: 20

Pagination

This method returns paginated results. The response includes a links.pages object with URLs for navigating between pages. To retrieve the next page, parse the next URL and pass the page parameter:

from urllib.parse import urlparse, parse_qs

resp = client.users.list()
pages = resp.get("links", {}).get("pages", {})

while "next" in pages:
    parsed = urlparse(pages["next"])
    page = int(parse_qs(parsed.query)["page"][0])
    resp = client.users.list(page=page)
    pages = resp.get("links", {}).get("pages", {})

Response Example

{
  "user_ids": [
    "alice",
    "bob"
  ],
  "pagination": {
    "page": 1,
    "per_page": 20,
    "total": 2
  }
}

More Information

See /v2/action-gateway/users in the API reference for additional detail on responses, headers, parameters, and more.