Give Feedback

pydo.sessions.list()

Generated on 1 Oct 2026 from pydo version v0.43.0

Copy page as Markdown View page as Markdown

Usage

client.sessions.list(
    end_user_id=None,
    page=1,
    per_page=20,
)

Returns JSONRaises HttpResponseError

Description

Returns the sessions you can see, newest first. Offset-paged with page and per_page; end_user_id filters to one actor.

Parameters

end_user_id string optional

Optional actor_id, matched exactly.

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.sessions.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.sessions.list(page=page)
    pages = resp.get("links", {}).get("pages", {})

Response Example

Show Response Example

{
  "sessions": [
    {
      "sessionUrn": "do:managed_agent_session:2b3c9f0e-1a4d-4e5f-8a7b-6c5d4e3f2a1b",
      "policy": {
        "defaultAction": "ask",
        "rules": [
          {
            "tool": "toolbelt:search-toolbelt@1",
            "match": {},
            "action": "allow"
          },
          {
            "tool": "jira_create_issue",
            "match": {},
            "action": "ask"
          }
        ]
      },
      "createdAt": "2026-09-24T12:00:00Z",
      "updatedAt": "2026-09-24T12:00:00Z",
      "name": "support-bot-alice",
      "actorId": "alice",
      "tools": {
        "references": [
          {
            "kind": "SESSION_TOOL_REFERENCE_KIND_TOOLBELT",
            "name": "search-toolbelt",
            "version": "1"
          },
          {
            "kind": "SESSION_TOOL_REFERENCE_KIND_TOOL",
            "name": "jira_create_issue",
            "version": "1"
          }
        ]
      },
      "config": {
        "preloadTools": [
          "exa_web_search"
        ],
        "outputViews": {
          "exa_web_search": "titles-and-urls"
        }
      },
      "agentUrn": "",
      "agentName": "",
      "owning_user_id": "2f8e1c3a-6b4d-4f7e-9a1c-5d3b7e9f1a2c"
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 20,
    "total": 1
  }
}

More Information

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