list_session_usage

Instructions

Implementation Reference

• servers/agentql/server.py:1340-1383 (handler)

  The main handler function for the list_session_usage MCP tool. It accepts optional filter parameters (sub_user_id, session_id, start_after, end_before, status, limit, page), constructs a validated request model, and sends a GET request to /v1/tetra/usage with query parameters. Registered via @mcp.tool() decorator.

  @mcp.tool()
  async def list_session_usage(
      sub_user_id: str | None = Field(None, description="Filter results to only include sessions belonging to a specific sub-user under the authenticated account."),
      session_id: str | None = Field(None, description="Filter results to a specific browser session by its unique session identifier."),
      start_after: str | None = Field(None, description="Return only sessions that started after this timestamp, specified in ISO 8601 date-time format."),
      end_before: str | None = Field(None, description="Return only sessions that ended before this timestamp, specified in ISO 8601 date-time format."),
      status: Literal["running", "ended"] | None = Field(None, description="Filter sessions by their current lifecycle status; use 'running' for active sessions or 'ended' for completed sessions."),
      limit: int | None = Field(None, description="Maximum number of session records to return per page; must be between 1 and 1000.", ge=1, le=1000),
      page: int | None = Field(None, description="Page number to retrieve for paginated results; must be 1 or greater.", ge=1),
  ) -> dict[str, Any] | ToolResult:
      """Retrieve a paginated list of Tetra browser session usage records for the authenticated user, with optional filtering by user, session, time range, and status."""
  
      # Construct request model with validation
      try:
          _request = _models.ListSessionUsageV1TetraUsageGetRequest(
              query=_models.ListSessionUsageV1TetraUsageGetRequestQuery(sub_user_id=sub_user_id, session_id=session_id, start_after=start_after, end_before=end_before, status=status, limit=limit, page=page)
          )
      except pydantic.ValidationError as _validation_err:
          logging.error(f"Parameter validation failed for list_session_usage: {_validation_err}")
          raise ValueError(f"Invalid parameters: {_validation_err.errors()}") from _validation_err
  
      # Extract parameters for API call
      _http_path = "/v1/tetra/usage"
      _http_query = _request.query.model_dump(by_alias=True, exclude_none=True) if _request.query else {}
      _http_headers = {}
  
      # Inject per-operation authentication
      _auth = await _get_auth_for_operation("list_session_usage")
      _http_headers.update(_auth.get("headers", {}))
  
      _request_id = str(uuid.uuid4())
      _log_tool_invocation("list_session_usage", "GET", _http_path, _request_id)
  
      # Execute request (returns normalized dict and status code)
      _response_data, _ = await _execute_tool_request(
          tool_name="list_session_usage",
          method="GET",
          path=_http_path,
          request_id=_request_id,
          params=_http_query,
          headers=_http_headers,
      )
  
      return _response_data

• servers/agentql/_models.py:60-71 (schema)

  Pydantic schema models for list_session_usage request validation. ListSessionUsageV1TetraUsageGetRequestQuery defines the 7 optional query filter parameters (sub_user_id, session_id, start_after, end_before, status, limit, page). ListSessionUsageV1TetraUsageGetRequest wraps the query.

  # Operation: list_session_usage
  class ListSessionUsageV1TetraUsageGetRequestQuery(StrictModel):
      sub_user_id: str | None = Field(default=None, description="Filter results to only include sessions belonging to a specific sub-user under the authenticated account.")
      session_id: str | None = Field(default=None, description="Filter results to a specific browser session by its unique session identifier.")
      start_after: str | None = Field(default=None, description="Return only sessions that started after this timestamp, specified in ISO 8601 date-time format.", json_schema_extra={'format': 'date-time'})
      end_before: str | None = Field(default=None, description="Return only sessions that ended before this timestamp, specified in ISO 8601 date-time format.", json_schema_extra={'format': 'date-time'})
      status: Literal["running", "ended"] | None = Field(default=None, description="Filter sessions by their current lifecycle status; use 'running' for active sessions or 'ended' for completed sessions.")
      limit: int | None = Field(default=None, description="Maximum number of session records to return per page; must be between 1 and 1000.", ge=1, le=1000)
      page: int | None = Field(default=None, description="Page number to retrieve for paginated results; must be 1 or greater.", ge=1)
  class ListSessionUsageV1TetraUsageGetRequest(StrictModel):
      """Retrieve a paginated list of Tetra browser session usage records for the authenticated user, with optional filtering by user, session, time range, and status."""
      query: ListSessionUsageV1TetraUsageGetRequestQuery | None = None

• servers/agentql/server.py:1339-1340 (registration)

  Tool registration via the @mcp.tool() decorator from FastMCP on the list_session_usage async function.

  # Tags: AgentQL Tetra (Remote Chrome Browser)
  @mcp.tool()

• servers/agentql/_auth.py:109-114 (helper)

  Auth registration mapping dict that maps the list_session_usage operation to require APIKeyHeader authentication.

  OPERATION_AUTH_MAP: dict[str, list[list[str]]] = {
      "query_webpage_data": [["APIKeyHeader"]],
      "get_usage": [["APIKeyHeader"]],
      "create_browser_session": [["APIKeyHeader"]],
      "list_session_usage": [["APIKeyHeader"]]
  }