DigitalOcean API (unofficial showcase)
GET/v2/agents/sessions

ListSessions enumerates sessions for the caller's tenant.

Keyset-paginated on an opaque cursor. Results are scoped to the authenticated team. Destroyed and failed sessions are omitted by default (matching the Cloud Console); pass status=SESSION_STATUS_ALL to list every session regardless of status, or an explicit status such as status=SESSION_STATUS_FAILED or status=SESSION_STATUS_DESTROYED to list only those.

5 parameters
page_sizeintegeroptional
Page size. Defaults to 50 when omitted or non-positive; values above 200 are clamped to 200 (not rejected).
Default:50
page_tokenstringoptional
Opaque keyset cursor returned by the previous page. Empty starts from the beginning.
statusstringoptional
Optional filter on session status. Empty / SESSION_STATUS_UNSPECIFIED means no explicit filter, which still hides destroyed and failed sessions by default; SESSION_STATUS_ALL opts out and returns every session regardless of status (no session is ever actually in this status; it only means something as a filter value here); any other explicit status overrides the default.
Allowed:SESSION_STATUS_UNSPECIFIEDSESSION_STATUS_PROVISIONINGSESSION_STATUS_READYSESSION_STATUS_DETACHEDSESSION_STATUS_DESTROYINGSESSION_STATUS_DESTROYEDSESSION_STATUS_FAILEDSESSION_STATUS_PAUSEDSESSION_STATUS_ALLSESSION_STATUS_LOCKEDDefault:SESSION_STATUS_UNSPECIFIED
namestringoptional
Optional exact-name filter (case-insensitive). Returns the single live (non-terminal) session that currently holds this name for the caller's team, or an empty list if none does. Matches the live holder only, so historical terminal rows and reused names never make it ambiguous (per-team live-name uniqueness bounds it to at most one). This is how clients (doctl / Console) resolve a session name to its id; the {session_id} path stays UUID-only.
searchstringoptional
Optional case-insensitive substring filter on session name (contains), for callers that don't know the exact name (e.g. a UI search box). Unlike `name`, this may return zero, one, or many sessions, including terminal ones. Independent of `name`; at most 64 characters.

7 status codes
200A successful response.
sessionsarray<object>optional
next_page_tokenstringoptional
Opaque cursor for the next page. Empty when there are no further pages.
400Invalid page_token.
idstringrequired
A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."
messagestringrequired
A message providing additional information about the error, including details to help resolve it when possible.
request_idstringoptional
Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.
401Authentication failed due to invalid credentials.
idstringrequired
A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."
messagestringrequired
A message providing additional information about the error, including details to help resolve it when possible.
request_idstringoptional
Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.
404The resource was not found.
idstringrequired
A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."
messagestringrequired
A message providing additional information about the error, including details to help resolve it when possible.
request_idstringoptional
Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.
429The API rate limit has been exceeded.
idstringrequired
A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."
messagestringrequired
A message providing additional information about the error, including details to help resolve it when possible.
request_idstringoptional
Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.
500There was a server error.
idstringrequired
A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."
messagestringrequired
A message providing additional information about the error, including details to help resolve it when possible.
request_idstringoptional
Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.
defaultThere was an unexpected error.
idstringrequired
A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."
messagestringrequired
A message providing additional information about the error, including details to help resolve it when possible.
request_idstringoptional
Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

Error handling

A 400 is returned: Invalid page_token. A 401 is returned: Authentication failed due to invalid credentials. A 404 is returned: The resource was not found. A 429 is returned: The API rate limit has been exceeded. A 500 is returned: There was a server error. Any other status is an error: There was an unexpected error.