The Session Class

class webuntis.Session(**config)

The origin of everything you want to do with the WebUntis API. Can be used as a context-manager to provide automatic log-out.

Configuration can be set with keyword arguments when initializing Session. Unless noted otherwise, they get saved in a dictionary located in the instance’s config attribute and can be modified afterwards.

  • username (str) – The username used for the API.
  • password (str) – The password used for the API.
  • server (str) –

    A host name, a URL, or a URL without path.

    s = webuntis.Session(..., server='')
    # ''
    # Want to disable SSL?
    # make sure there's NO SLASH at the end!
    s.config['server'] = ''
    # ''
    # or maybe use a completely different API endpoint?
    s.config['server'] = ''
    # ''
    # or just change the path?
    s.config['server'] = ''
    # ''
    s.config['server'] = '!"$%/WebUntis/'
    # ValueError: Not a valid hostname
  • school (str) – A valid school name.
  • useragent (str) – A string containing a useragent. Please include useful information, such as an email address, for the server maintainer. Just like you would do with the HTTP useragents of bots.
  • cachelen (int) –

    The maximum size of the internal cache. All results are saved in it, but they only get used if you set the from_cache parameter on a session method to True. This parameter is not saved in the configuration dictionary.

    s.timetable(klasse=123)  # saves in cache
    s.timetable(klasse=123)  # fetch data again, override old value
    s.timetable(klasse=123, from_cache=True)  # get directly from cache

    The reason this cache was added is that the API only allows you to fetch a whole list of objects (teachers/schoolclasses/…), not single ones. It would seriously harm performance to fetch the whole list each time we want information about a single object. Without the cache, i sometimes experienced a performance decrease about twenty seconds, so i wouldn’t set the cachelen to anything smaller than 5.

    Default value is 20.

    You can clear the cache using:

    s.cache.clear('timetable')  # clears all cached timetables
    s.cache.clear()  # clears everything from the cache
  • jsessionid (str) – The session key to use. You usually shouldn’t touch this.
  • login_repeat (int) – The amount of times python-webuntis should try to login when finding no or an expired session. Default to 0, meaning it won’t do that.
  • use_cache (bool) – always use the cache

Initializes an authentication, provided we have the credentials for it.

Returns:The session. This is useful for jQuery-like command chaining:
s = webuntis.Session(...).login()
Raises:webuntis.errors.BadCredentialsError – Username/Password missing or invalid.
Raises:webuntis.errors.AuthError – Didn’t receive a session ID for unknown reasons.

Log out of session

Parameters:suppress_errors (bool) – Whether to suppress errors.
Raises:webuntis.errors.NotLoggedInError – Can’t log out because not logged in. Raised unless suppress_errors is True.
config = None

The config dictionary, filled with most keyword arguments from initialization.

cache = None

Contains the caching dictionary for requests.

Things you can do with the API

class webuntis.Session

Get all departments.

Return type:webuntis.objects.DepartmentList

Get all holidays.

Return type:webuntis.objects.HolidayList

Get all school classes.

Parameters:schoolyear (webuntis.objects.SchoolyearObject or an integer ID of it) – The schoolyear where the classes should be fetched from.
Return type:webuntis.objects.KlassenList
timetable(start, end, **type_and_id)

Get the timetable for a specific school class and time period.

Return type:


Furthermore you have to explicitly define a klasse, teacher, subject, room or student parameter containing the id or the object of the thing you want to get a timetable about:

import datetime
today =
monday = today - datetime.timedelta(days=today.weekday())
friday = monday + datetime.timedelta(days=4)

klasse = s.klassen().filter(id=1)[0]  # schoolclass #1
tt = s.timetable(klasse=klasse, start=monday, end=friday)
Raises:ValueError, TypeError

Get all rooms of a school.

Return type:webuntis.objects.RoomList

Get all schoolyears.

Return type:webuntis.objects.SchoolyearList

Get all subjects.

Return type:webuntis.objects.SubjectList

Get all teachers.

Return type:webuntis.objects.TeacherList

Information about lesson types and period codes, specifically about the colors used to highlight them in the web-interface of WebUntis.

Return type:webuntis.objects.StatusData

Information about the last change made.

Return type:py:class:webuntis.objects.TimeStampObject
substitutions(start, end, department_id=0)

Get all substitutions.

Return type:



Information about the Timegrid.

Return type:webuntis.objects.TimegridObject

Get all students

Return type:webuntis.objects.StudentsList

Information about the Exam types. needs additional rights Master/Exam Types – Stammdaten /Pruefungsart

Return type:webuntis.objects.ExamTypeList
exams(start, end, exam_type_id=0)

Information about the Exams.

Return type:


timetable_with_absences(start, end)

Information about the Exams.

Return type:


class_reg_events(start, end)

Information about the ClassRegEvents :type start: datetime.datetime or or int :param start: The beginning of the time period.

Parameters:end (datetime.datetime or or int) – The end of the time period.
Return type:webuntis.objects.ClassRegEventList